From 372de72b112b404bebad170c39d5b6444fbad094 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Wed, 21 Oct 2026 08:26:54 +0300 Subject: [PATCH 01/77] fix(session): tolerate historical verification mismatches Claude-Session-Id: 01a15cb6-ff42-75a0-8c3a-712b63716008 --- pkg/database/prompt_run_iteration_store.go | 4 +- ...ation_store_validation_integration_test.go | 19 +++-- pkg/session/query/query.go | 2 +- .../query/verification_history_ginkgo_test.go | 79 +++++++++++++++++++ 4 files changed, 94 insertions(+), 10 deletions(-) create mode 100644 pkg/session/query/verification_history_ginkgo_test.go diff --git a/pkg/database/prompt_run_iteration_store.go b/pkg/database/prompt_run_iteration_store.go index be558105..b210980e 100644 --- a/pkg/database/prompt_run_iteration_store.go +++ b/pkg/database/prompt_run_iteration_store.go @@ -7,6 +7,7 @@ import ( "time" "github.com/flanksource/captain/pkg/api" + "github.com/flanksource/commons/logger" "github.com/google/uuid" "gorm.io/gorm/clause" ) @@ -275,8 +276,7 @@ func (db *DB) latestPromptRunVerifications(ctx context.Context, runIDs []uuid.UU record.PromptRunID, record.Iteration, err) } if err := report.Validate(); err != nil { - return nil, fmt.Errorf("verification result of Captain prompt run %s iteration %d is corrupt: %w", - record.PromptRunID, record.Iteration, err) + logger.Warnf("inconsistent verification result of Captain prompt run %s iteration %d: %v", record.PromptRunID, record.Iteration, err) } latest[record.PromptRunID] = promptRunVerification{Iteration: record.Iteration, Report: &report} } diff --git a/pkg/database/prompt_run_iteration_store_validation_integration_test.go b/pkg/database/prompt_run_iteration_store_validation_integration_test.go index a74bd516..4a99ad62 100644 --- a/pkg/database/prompt_run_iteration_store_validation_integration_test.go +++ b/pkg/database/prompt_run_iteration_store_validation_integration_test.go @@ -55,11 +55,8 @@ func TestPromptRunIterationRejectsInvalidInputBeforeWriting(t *testing.T) { assert.ErrorIs(t, err, ErrInvalidPromptRun) } -// TestPromptRunVerificationReaderRejectsCorruptStoredReports covers rows the store -// itself would never write: a JSONB `null` (which passes `IS NOT NULL`) must not -// decode into a blank passing report, and a report that fails Validate must surface -// as an error rather than render as an empty verdict. -func TestPromptRunVerificationReaderRejectsCorruptStoredReports(t *testing.T) { +// Historical reports retain their evidence even when current validation rejects them. +func TestPromptRunVerificationReaderPreservesInconsistentStoredReports(t *testing.T) { db := openPromptRunIterationDB(t, "captain_prompt_run_iteration_corrupt") jsonNullRun := newPromptRunForIterations(t, db) @@ -85,9 +82,17 @@ func TestPromptRunVerificationReaderRejectsCorruptStoredReports(t *testing.T) { corruptRun := newPromptRunForIterations(t, db) insertRawIterationVerification(t, db, corruptRun.ID, 1, `{"kind":"cmd","name":"corrupt","ran":true,"passed":true,"state":"failed","summary":{}}`) + report, verified, err = db.LatestPromptRunVerification(t.Context(), corruptRun.ID) + require.NoError(t, err) + require.NotNil(t, report) + assert.Equal(t, 1, verified) + assert.True(t, report.Passed) + assert.EqualValues(t, "failed", report.State) + assert.EqualError(t, report.Validate(), `verify report "corrupt": passed=true with state "failed"`) + + insertRawIterationVerification(t, db, corruptRun.ID, 2, `{"tests":"not an array"}`) _, _, err = db.LatestPromptRunVerification(t.Context(), corruptRun.ID) - require.Error(t, err, "a stored report that fails Validate must surface, not render as a blank pass") - assert.Contains(t, err.Error(), "passed=true with state") + require.ErrorContains(t, err, "decode verification result") } func insertRawIterationVerification(t *testing.T, db *DB, runID uuid.UUID, iteration int, verification string) { diff --git a/pkg/session/query/query.go b/pkg/session/query/query.go index 87d54228..fec8fd4a 100644 --- a/pkg/session/query/query.go +++ b/pkg/session/query/query.go @@ -69,7 +69,7 @@ func ComposeSession( for _, iteration := range iterations { if iteration.VerificationResult != nil { if err := iteration.VerificationResult.Validate(); err != nil { - return load.Result{}, nil, fmt.Errorf("invalid verification for Captain prompt run %s iteration %d: %w", runs[0].ID, iteration.Iteration, err) + logger.Warnf("inconsistent verification result of Captain prompt run %s iteration %d: %v", runs[0].ID, iteration.Iteration, err) } facts.Verifications = append(facts.Verifications, session.Verification{Iteration: iteration.Iteration, Report: *iteration.VerificationResult}) } diff --git a/pkg/session/query/verification_history_ginkgo_test.go b/pkg/session/query/verification_history_ginkgo_test.go new file mode 100644 index 00000000..1f4acfdc --- /dev/null +++ b/pkg/session/query/verification_history_ginkgo_test.go @@ -0,0 +1,79 @@ +package query + +import ( + "encoding/json" + + "github.com/flanksource/captain/pkg/api" + "github.com/flanksource/captain/pkg/database" + "github.com/flanksource/captain/pkg/session" + "github.com/flanksource/commons-db/dbtest" + "github.com/google/uuid" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("Verification history", func() { + It("preserves inconsistent reports in single reads, batches and composed sessions", func(ctx SpecContext) { + handle := dbtest.ForGinkgo(dbtest.Options{Name: "captain_verification_history"}) + db, err := database.Open(ctx, database.WithDSN(handle.DSN()), database.WithMigrations()) + Expect(err).NotTo(HaveOccurred()) + DeferCleanup(func() { Expect(db.Close()).To(Succeed()) }) + + created, err := db.CreateOrGetSession(ctx, database.CreateSessionInput{ + ProviderSessionID: uuid.NewString(), Source: "codex", Provider: "openai", + }) + Expect(err).NotTo(HaveOccurred()) + run, err := db.CreatePromptRun(ctx, database.CreatePromptRunInput{SessionID: created.ID}) + Expect(err).NotTo(HaveOccurred()) + summary := api.VerifySummary{Total: 617, Passed: 616, Skipped: 1} + historical := api.VerifyReport{ + Kind: api.VerifyKindFixture, Name: "fixture", Ran: true, Iteration: 1, + State: api.VerifyStateSkipped, Summary: summary, + Tests: []api.VerifyNode{{Name: "test suite", Summary: &summary}}, + } + Expect(historical.Validate()).To(MatchError(ContainSubstring(`state "skipped" but its tests are "passed"`))) + raw, err := json.Marshal(historical) + Expect(err).NotTo(HaveOccurred()) + Expect(db.Gorm().Exec(`INSERT INTO captain_prompt_run_iterations + (prompt_run_id, iteration, state, verification_result) VALUES (?, 1, 'failed', ?::jsonb)`, + run.ID, string(raw)).Error).To(Succeed()) + + report, iteration, err := db.LatestPromptRunVerification(ctx, run.ID) + Expect(err).NotTo(HaveOccurred()) + Expect(iteration).To(Equal(1)) + Expect(report).To(Equal(&historical)) + + validSession, err := db.CreateOrGetSession(ctx, database.CreateSessionInput{ + ProviderSessionID: uuid.NewString(), Source: "codex", Provider: "openai", + }) + Expect(err).NotTo(HaveOccurred()) + validRun, err := db.CreatePromptRun(ctx, database.CreatePromptRunInput{SessionID: validSession.ID}) + Expect(err).NotTo(HaveOccurred()) + valid := api.NewNodeReport(api.VerifyKindFixture, "valid", api.VerifyNode{Name: "check", Passed: true}) + _, err = db.UpsertPromptRunIteration(ctx, database.UpsertPromptRunIterationInput{ + PromptRunID: validRun.ID, Iteration: 1, State: database.PromptRunIterationStateSucceeded, + VerificationResult: &valid, + }) + Expect(err).NotTo(HaveOccurred()) + batch, err := db.LatestPromptRunVerifications(ctx, []uuid.UUID{run.ID, validRun.ID}) + Expect(err).NotTo(HaveOccurred()) + Expect(batch).To(Equal(map[uuid.UUID]database.PromptRunVerification{ + run.ID: {Iteration: 1, Report: &historical}, validRun.ID: {Iteration: 1, Report: &valid}, + })) + + overview, err := db.GetSessionOverviewByIdentity(ctx, created.ID.String()) + Expect(err).NotTo(HaveOccurred()) + result, failures, err := ComposeSession(ctx, db, *overview, ComposeOptions{ + Transcript: &session.Session{Messages: []session.Message{ + {ID: "transcript", Role: "user", Parts: []session.Part{{Type: session.PartText, Text: "original message"}}}, + }}, + }) + Expect(err).NotTo(HaveOccurred()) + Expect(failures).To(BeEmpty()) + Expect(result.Session.Verifications).To(Equal([]session.Verification{{Iteration: 1, Report: historical}})) + Expect(result.Session.Messages).To(ContainElement(HaveField("ID", "transcript"))) + iterations, err := db.ListPromptRunIterations(ctx, run.ID) + Expect(err).NotTo(HaveOccurred()) + Expect(iterations[0].VerificationResult).To(Equal(&historical)) + }) +}) From e955e8d37f2fad9a9df594b4928acfbd8fa31e26 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Wed, 21 Oct 2026 16:56:17 +0300 Subject: [PATCH 02/77] feat(ai): support DeepSeek Flash image attachments Gavel-Issue-Id: 9723fa02-92e0-4ae0-ae6f-1815602e2cba Claude-Session-Id: 01a15ea7-403c-7d71-854f-08688a7af676 --- pkg/ai/attachment_capabilities_ginkgo_test.go | 2 +- pkg/ai/deepseek_attachments_ginkgo_test.go | 65 +++++++++++ pkg/ai/prompt/README.md | 12 ++ .../deepseek_attachments_ginkgo_test.go | 105 ++++++++++++++++++ pkg/api/registry/media.go | 2 +- pkg/api/registry/providers.go | 4 +- 6 files changed, 185 insertions(+), 5 deletions(-) create mode 100644 pkg/ai/deepseek_attachments_ginkgo_test.go create mode 100644 pkg/ai/provider/genkit/deepseek_attachments_ginkgo_test.go diff --git a/pkg/ai/attachment_capabilities_ginkgo_test.go b/pkg/ai/attachment_capabilities_ginkgo_test.go index 8f33db99..b43a7806 100644 --- a/pkg/ai/attachment_capabilities_ginkgo_test.go +++ b/pkg/ai/attachment_capabilities_ginkgo_test.go @@ -64,7 +64,7 @@ var _ = Describe("Attachment capabilities", func() { Entry("Gemini API", api.Google, api.ModeAPI, []string{"image/*", "audio/*", "video/*", "application/pdf"}), Entry("Anthropic API", api.Anthropic, api.ModeAPI, []string{"image/*"}), Entry("OpenAI API", api.OpenAI, api.ModeAPI, []string{"image/*"}), - Entry("DeepSeek API", api.DeepSeek, api.ModeAPI, []string{}), + Entry("DeepSeek API", api.DeepSeek, api.ModeAPI, []string{"image/png", "image/jpeg", "image/gif", "image/webp"}), Entry("Codex agent", api.OpenAI, api.ModeAgent, []string{"image/*"}), Entry("Codex CLI", api.OpenAI, api.ModeCLI, []string{"image/*"}), Entry("Claude Agent", api.Anthropic, api.ModeAgent, []string{"image/png", "image/jpeg", "image/gif", "image/webp", "application/pdf"}), diff --git a/pkg/ai/deepseek_attachments_ginkgo_test.go b/pkg/ai/deepseek_attachments_ginkgo_test.go new file mode 100644 index 00000000..b2ca4eb3 --- /dev/null +++ b/pkg/ai/deepseek_attachments_ginkgo_test.go @@ -0,0 +1,65 @@ +package ai_test + +import ( + "github.com/flanksource/captain/pkg/ai" + "github.com/flanksource/captain/pkg/api" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("DeepSeek attachments", func() { + imageTypes := []string{"image/png", "image/jpeg", "image/gif", "image/webp"} + + DescribeTable("accepts supported images on Flash models", func(name string) { + model := resolved(api.Model{Name: name, Mode: api.ModeAPI}) + Expect(model.MediaTypes).To(ConsistOf(imageTypes)) + for _, mediaType := range imageTypes { + Expect(ai.ValidateAttachmentCompatibility([]api.Model{model}, []api.AttachmentRef{{MediaType: mediaType}})).To(Succeed()) + } + }, + Entry("rolling Flash", "deepseek-flash"), + Entry("V4 Flash alias", "deepseek-v4-flash"), + Entry("vision experiment alias", "deepseek-v4-flash-vision-exp"), + ) + + It("keeps Pro text-only even when the API adapter can carry images", func() { + model := resolved(api.Model{Name: "deepseek-v4-pro", Mode: api.ModeAPI}) + Expect(model.MediaTypes).To(BeEmpty()) + for _, mediaType := range imageTypes { + Expect(ai.ValidateAttachmentCompatibility([]api.Model{model}, []api.AttachmentRef{{MediaType: mediaType}})).To(MatchError(ContainSubstring("does not accept " + mediaType))) + } + }) + + DescribeTable("rejects unsupported attachment formats", func(mediaType string) { + model := resolved(api.Model{Name: "deepseek-flash", Mode: api.ModeAPI}) + Expect(ai.ValidateAttachmentCompatibility([]api.Model{model}, []api.AttachmentRef{{MediaType: mediaType}})).To(MatchError(ContainSubstring("does not accept " + mediaType))) + }, + Entry("SVG", "image/svg+xml"), + Entry("PDF", "application/pdf"), + Entry("audio", "audio/mpeg"), + Entry("video", "video/mp4"), + ) + + It("publishes matching static and live catalog capabilities", func() { + static := ai.CatalogInfo([]string{"deepseek"}) + live := ai.CatalogInfoFromAdapters([]ai.AdapterStatus{{ + Provider: "deepseek", Mode: "api", + ModelDetails: []ai.ModelDef{ + {ID: "deepseek-flash", Provider: "deepseek", Mode: api.ModeAPI}, + {ID: "deepseek-v4-pro", Provider: "deepseek", Mode: api.ModeAPI}, + }, + }}) + for _, catalog := range [][]ai.ModelInfo{static, live} { + Expect(catalog).To(ContainElement(And( + HaveField("ID", "deepseek/deepseek-flash"), + HaveField("InputMediaTypes", ConsistOf(imageTypes)), + HaveField("Runtime.MediaTypes", ConsistOf(imageTypes)), + ))) + Expect(catalog).To(ContainElement(And( + HaveField("ID", "deepseek/deepseek-v4-pro"), + HaveField("InputMediaTypes", BeEmpty()), + HaveField("Runtime.MediaTypes", BeEmpty()), + ))) + } + }) +}) diff --git a/pkg/ai/prompt/README.md b/pkg/ai/prompt/README.md index bbc86b1e..76bbb939 100644 --- a/pkg/ai/prompt/README.md +++ b/pkg/ai/prompt/README.md @@ -26,3 +26,15 @@ Run the focused rendering and transport examples/tests from the Captain checkout go test ./pkg/ai/prompt -run '^TestPromptDocuments$' -ginkgo.focus='Declared prompt rendering' -count=1 go test ./pkg/ai -run '^TestAttachmentCapabilities$' -ginkgo.focus='Named prompt Spec transport' -count=1 ``` + +## DeepSeek image attachments + +`deepseek-flash` accepts PNG, JPEG, GIF, and WebP images. The `deepseek-v4-flash` and `deepseek-v4-flash-vision-exp` names accept the same formats. `deepseek-v4-pro` is text-only; PDF, SVG, audio, and video attachments are rejected. + +Set `DEEPSEEK_API_KEY`, then attach an existing image to a prompt: + +```sh +captain prompt run --model api:deepseek-flash --attach chart.png "Describe this chart." +``` + +For Go callers, put references in `Spec.Prompt.Attachments` or user-message attachment parts and resolve them with the attachment store before execution. Captain sends prepared images inline through the existing OpenAI-compatible Chat Completions endpoint; it does not upload them to DeepSeek's Files API. diff --git a/pkg/ai/provider/genkit/deepseek_attachments_ginkgo_test.go b/pkg/ai/provider/genkit/deepseek_attachments_ginkgo_test.go new file mode 100644 index 00000000..c773a5c7 --- /dev/null +++ b/pkg/ai/provider/genkit/deepseek_attachments_ginkgo_test.go @@ -0,0 +1,105 @@ +package genkit + +import ( + "context" + "encoding/json" + "io" + "net/http" + "net/http/httptest" + "strings" + + "github.com/flanksource/captain/pkg/ai" + "github.com/flanksource/captain/pkg/api" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("DeepSeek image transport", func() { + DescribeTable("sends ordered text and images to chat completions", func(conversation, streaming bool) { + requests := make(chan map[string]any, 1) + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + defer GinkgoRecover() + Expect(r.Method).To(Equal(http.MethodPost)) + Expect(r.URL.Path).To(Equal("/chat/completions")) + var body map[string]any + Expect(json.NewDecoder(r.Body).Decode(&body)).To(Succeed()) + requests <- body + if streaming { + w.Header().Set("Content-Type", "text/event-stream") + _, err := io.WriteString(w, "data: {\"id\":\"example\",\"object\":\"chat.completion.chunk\",\"model\":\"deepseek-flash\",\"choices\":[{\"index\":0,\"delta\":{\"role\":\"assistant\",\"content\":\"A chart.\"},\"finish_reason\":null}]}\n\ndata: {\"id\":\"example\",\"object\":\"chat.completion.chunk\",\"model\":\"deepseek-flash\",\"choices\":[{\"index\":0,\"delta\":{},\"finish_reason\":\"stop\"}]}\n\ndata: [DONE]\n\n") + Expect(err).NotTo(HaveOccurred()) + return + } + w.Header().Set("Content-Type", "application/json") + _, err := io.WriteString(w, `{"id":"example","object":"chat.completion","model":"deepseek-flash","choices":[{"index":0,"message":{"role":"assistant","content":"A chart."},"finish_reason":"stop"}],"usage":{"prompt_tokens":10,"completion_tokens":3,"total_tokens":13}}`) + Expect(err).NotTo(HaveOccurred()) + })) + DeferCleanup(server.Close) + model, err := api.ResolveModel(api.Model{Name: "deepseek-flash", Mode: api.ModeAPI}) + Expect(err).NotTo(HaveOccurred()) + provider, err := New(ai.Config{Model: model, APIKey: "example-key", APIURL: server.URL}) + Expect(err).NotTo(HaveOccurred()) + first := api.AttachmentRef{ID: api.AttachmentIDPrefix + strings.Repeat("a", 64), MediaType: "image/png"}. + WithPreparedContent(api.AttachmentContent{Bytes: []byte("first")}) + second := api.AttachmentRef{ID: api.AttachmentIDPrefix + strings.Repeat("b", 64), MediaType: "image/jpeg"}. + WithPreparedContent(api.AttachmentContent{Bytes: []byte("second")}) + request := ai.Request{Model: model, Prompt: api.Prompt{User: "Compare charts.", Attachments: []api.AttachmentRef{first, second}}} + if conversation { + request.Prompt = api.Prompt{} + request.Messages = []api.Message{{Role: api.RoleUser, Parts: []api.Part{ + {Type: api.PartText, Text: "Compare charts."}, + {Type: api.PartAttachment, Attachment: &first}, + {Type: api.PartAttachment, Attachment: &second}, + }}} + } + if streaming { + events, err := provider.ExecuteStream(context.Background(), request) + Expect(err).NotTo(HaveOccurred()) + var text string + var complete bool + for event := range events { + Expect(event.Kind).NotTo(Equal(ai.EventError), event.Error) + if event.Kind == ai.EventText { + text += event.Text + } + complete = complete || event.Kind == ai.EventResult + } + Expect(text).To(Equal("A chart.")) + Expect(complete).To(BeTrue()) + } else { + response, err := provider.Execute(context.Background(), request) + Expect(err).NotTo(HaveOccurred()) + Expect(response.Text).To(Equal("A chart.")) + } + var body map[string]any + Expect(requests).To(Receive(&body)) + Expect(body["model"]).To(Equal(model.Name)) + if streaming { + Expect(body).To(HaveKeyWithValue("stream", true)) + } else { + Expect(body).NotTo(HaveKey("stream")) + } + Expect(body["messages"]).To(Equal([]any{map[string]any{ + "role": "user", "content": []any{ + map[string]any{"type": "text", "text": "Compare charts."}, + map[string]any{"type": "image_url", "image_url": map[string]any{"url": "data:image/png;base64,Zmlyc3Q="}}, + map[string]any{"type": "image_url", "image_url": map[string]any{"url": "data:image/jpeg;base64,c2Vjb25k"}}, + }, + }})) + }, + Entry("buffered prompt", false, false), + Entry("streaming prompt", false, true), + Entry("buffered conversation", true, false), + Entry("streaming conversation", true, true), + ) + + It("rejects unresolved Flash images before sending a request", func() { + model, err := api.ResolveModel(api.Model{Name: "deepseek-flash", Mode: api.ModeAPI}) + Expect(err).NotTo(HaveOccurred()) + provider := &Provider{provider: ai.DeepSeek, cfg: ai.Config{Model: model}, modelRef: "deepseek/deepseek-flash"} + _, err = provider.Execute(context.Background(), ai.Request{Model: model, Prompt: api.Prompt{ + Attachments: []api.AttachmentRef{{Path: "chart.png", MediaType: "image/png"}}, + }}) + Expect(err).To(MatchError(ContainSubstring("is not prepared"))) + }) +}) diff --git a/pkg/api/registry/media.go b/pkg/api/registry/media.go index 01584d8e..876c4101 100644 --- a/pkg/api/registry/media.go +++ b/pkg/api/registry/media.go @@ -15,7 +15,7 @@ func (p *Provider) MediaTypesFor(mode RuntimeMode, model string) []string { return []string{} } modelTypes := caps.MediaTypes - if m, found := p.Lookup(model); found && len(m.InputMediaTypes) > 0 { + if m, found := p.Lookup(model); found { modelTypes = m.InputMediaTypes } return ClampMediaTypes(caps.MediaTypes, modelTypes) diff --git a/pkg/api/registry/providers.go b/pkg/api/registry/providers.go index ecce3768..afe3aed2 100644 --- a/pkg/api/registry/providers.go +++ b/pkg/api/registry/providers.go @@ -91,9 +91,7 @@ var ( EnvVars: []string{"DEEPSEEK_API_KEY"}, DefaultMode: ModeAPI, modes: map[RuntimeMode]ModeCapabilities{ - // DeepSeek selects reasoning by model id (deepseek-reasoner vs - // deepseek-chat) and ships no attachment support. - ModeAPI: {Streaming: true, CallerTools: true}, + ModeAPI: {Streaming: true, CallerTools: true, MediaTypes: []string{"image/png", "image/jpeg", "image/gif", "image/webp"}}, }, claimPrefixes: []string{"deepseek"}, families: []string{"deepseek"}, From 3a301536850d382ddd1ddcd36b3f3ac25850701a Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Wed, 21 Oct 2026 18:26:59 +0300 Subject: [PATCH 03/77] fix(ai): route prompt questions through an available broker Claude-Session-Id: 01a15e89-a154-70d0-beff-58fa5d2ba7b1 --- Taskfile.yaml | 1 + docs/src/pages/agents/approvals.mdx | 14 ++++ pkg/ai/agent/runner.go | 8 +- pkg/ai/provider/claudeagent/agent.ts | 1 + pkg/ai/provider/claudeagent/provider.go | 20 +++-- pkg/ai/provider/claudeagent/provider_test.go | 2 +- pkg/ai/provider/coalesce.go | 11 +-- pkg/ai/provider/codex_appserver.go | 2 + pkg/ai/provider/codex_appserver_process.go | 3 +- pkg/ai/provider/codex_appserver_question.go | 14 ++-- pkg/ai/provider/codex_appserver_test.go | 2 + pkg/ai/question_policy.go | 11 +++ pkg/ai/terminal_outcome_tracker.go | 47 +++++++++++ pkg/cli/ai.go | 20 ++++- pkg/cli/ai_options.go | 2 + pkg/cli/prompt_run.go | 23 ++++-- pkg/cli/prompt_run_live.go | 18 ++++- pkg/cli/prompt_run_terminal.go | 43 +++++++++++ pkg/cli/testdata/prompt-questions/README.md | 29 +++++++ .../prompt-questions/buffered.fixture.yaml | 56 ++++++++++++++ .../prompt-questions/codex.aimock.yaml | 42 ++++++++++ .../prompt-questions/codex.fixture.yaml | 75 ++++++++++++++++++ .../noninteractive.fixture.yaml | 49 ++++++++++++ .../prompt-questions/policy.aimock.yaml | 15 ++++ .../prompt-questions/question.aimock.yaml | 31 ++++++++ .../redirected-stdout.fixture.yaml | 61 +++++++++++++++ .../prompt-questions/streamed.fixture.yaml | 56 ++++++++++++++ .../terminal-policy.fixture.yaml | 65 ++++++++++++++++ .../prompt-questions/workflow.fixture.yaml | 77 +++++++++++++++++++ .../testdata/prompt-questions/workflow.prompt | 12 +++ 30 files changed, 766 insertions(+), 44 deletions(-) create mode 100644 pkg/ai/question_policy.go create mode 100644 pkg/ai/terminal_outcome_tracker.go create mode 100644 pkg/cli/prompt_run_terminal.go create mode 100644 pkg/cli/testdata/prompt-questions/README.md create mode 100644 pkg/cli/testdata/prompt-questions/buffered.fixture.yaml create mode 100644 pkg/cli/testdata/prompt-questions/codex.aimock.yaml create mode 100644 pkg/cli/testdata/prompt-questions/codex.fixture.yaml create mode 100644 pkg/cli/testdata/prompt-questions/noninteractive.fixture.yaml create mode 100644 pkg/cli/testdata/prompt-questions/policy.aimock.yaml create mode 100644 pkg/cli/testdata/prompt-questions/question.aimock.yaml create mode 100644 pkg/cli/testdata/prompt-questions/redirected-stdout.fixture.yaml create mode 100644 pkg/cli/testdata/prompt-questions/streamed.fixture.yaml create mode 100644 pkg/cli/testdata/prompt-questions/terminal-policy.fixture.yaml create mode 100644 pkg/cli/testdata/prompt-questions/workflow.fixture.yaml create mode 100644 pkg/cli/testdata/prompt-questions/workflow.prompt diff --git a/Taskfile.yaml b/Taskfile.yaml index 4aac9cd5..fd06bbe0 100644 --- a/Taskfile.yaml +++ b/Taskfile.yaml @@ -134,6 +134,7 @@ tasks: cmds: - PATH="$PWD/.bin:$PATH" gavel fixtures pkg/cli/testdata/history_test.md - PATH="$PWD/.bin:$PATH" gavel fixtures pkg/cli/testdata/permissions_matrix_test.md + - gavel fixtures 'pkg/cli/testdata/prompt-questions/*.fixture.yaml' install: desc: Build and install captain to the default Go bin diff --git a/docs/src/pages/agents/approvals.mdx b/docs/src/pages/agents/approvals.mdx index 5e137f83..d2dfc8e1 100644 --- a/docs/src/pages/agents/approvals.mdx +++ b/docs/src/pages/agents/approvals.mdx @@ -37,6 +37,20 @@ Two rules apply to every callback: - **Deny is a hard floor.** A tool the run's permission strategy denies, and anything plan mode forbids, is rejected before `OnApproval` runs. No row is written and no event is sent, and no decision, scope, or grant can override it. - **Any approval may escalate.** An approved `command`, `filesystem`, `network`, or `permissions` request can go beyond the run's initial sandbox posture. `Escalates` marks the ones that do. +## Foreground terminal runs + +A single-runtime `captain prompt run` using Claude Agent or Codex app-server attaches `approval.Terminal` when stdin and stderr are terminals. Native questions and permission requests draw on stderr and read answers from stdin. The event renderer pauses while a form is open, and execution resumes with the selected answer. + +```sh +captain prompt run --model agent:haiku --edit -p "Inspect the project and ask through the question tool if a required decision is missing." +``` + +Redirecting stdout preserves the answer channel, including JSON output. `--no-stream` also permits terminal questions. Piped input, redirected stderr, and concurrent multi-model comparisons have no terminal broker. Explicit Claude `bypassPermissions` keeps that permission mode and disables terminal questions. + +Both agent runtimes disable their native question tool when no broker exists. Codex permits blocking questions in plan mode; default mode keeps questions disabled because its native questions are nonblocking. When questions are unavailable, instructions require the agent to complete independently within the authorized scope or report an unresolved blocker without asking questions. When available, instructions require the native question tool and an answer before continuing. These instructions preserve the prompt's response format; they do not classify arbitrary final prose as a question. + +HTTP runs use their host's configured broker and never inherit the server process's terminal. An explicitly supplied `Config.OnApproval` callback remains authoritative. Answered or refused native question calls are resolved by their tool-call IDs; an outstanding native question cannot make a foreground run succeed. + ## Migrating from `CanUseTool` The approval callback was renamed and widened. The old names remain as deprecated aliases until the unified-approval Phase 6. diff --git a/pkg/ai/agent/runner.go b/pkg/ai/agent/runner.go index 0508804f..a24dca90 100644 --- a/pkg/ai/agent/runner.go +++ b/pkg/ai/agent/runner.go @@ -341,14 +341,11 @@ func (r *Runner[T]) updateResponse(hc *HookContext, prev *ai.LoopIteration) erro ws.SessionID = prev.SessionID } var text strings.Builder + var terminal ai.TerminalOutcomeTracker for _, ev := range prev.Events { - outcome, err := ai.TerminalOutcomeFromEvent(ev) - if err != nil { + if err := terminal.Observe(ev); err != nil { return fmt.Errorf("agent: invalid terminal outcome: %w", err) } - if outcome != nil { - hc.Response.TerminalOutcome = outcome - } switch ev.Kind { case ai.EventText: text.WriteString(ev.Text) @@ -358,6 +355,7 @@ func (r *Runner[T]) updateResponse(hc *HookContext, prev *ai.LoopIteration) erro } } } + hc.Response.TerminalOutcome = terminal.Outcome() hc.Response.Text = text.String() hc.Response.Usage = prev.Usage return nil diff --git a/pkg/ai/provider/claudeagent/agent.ts b/pkg/ai/provider/claudeagent/agent.ts index f31c30fd..36fb7da6 100644 --- a/pkg/ai/provider/claudeagent/agent.ts +++ b/pkg/ai/provider/claudeagent/agent.ts @@ -153,6 +153,7 @@ function buildOptions(params: InitializeParams): Options { maxTurns: params.maxTurns || undefined, maxBudgetUsd: params.maxBudgetUsd || undefined, permissionMode, + permissionPrompts: brokered ? "host" : "none", // Stream text and thinking as they are produced. Without it the SDK reports // only whole assistant messages, so a host rendering live progress showed // nothing for the length of a reasoning block and then the whole block at diff --git a/pkg/ai/provider/claudeagent/provider.go b/pkg/ai/provider/claudeagent/provider.go index 00f417c2..a678d55f 100644 --- a/pkg/ai/provider/claudeagent/provider.go +++ b/pkg/ai/provider/claudeagent/provider.go @@ -190,17 +190,12 @@ func (p *Provider) Execute(ctx context.Context, req ai.Request) (*ai.Response, e success = true sawResult bool lastErr string - outcome *ai.TerminalOutcome + outcome ai.TerminalOutcomeTracker outcomeErr error ) for ev := range events { if outcomeErr == nil { - parsed, parseErr := ai.TerminalOutcomeFromEvent(ev) - if parseErr != nil { - outcomeErr = parseErr - } else if parsed != nil { - outcome = parsed - } + outcomeErr = outcome.Observe(ev) } switch ev.Kind { case ai.EventText: @@ -245,12 +240,12 @@ func (p *Provider) Execute(ctx context.Context, req ai.Request) (*ai.Response, e Runtime: ai.RuntimeOf(ai.Anthropic, ai.ModeAgent), Usage: usage, Duration: time.Since(start), - TerminalOutcome: outcome, + TerminalOutcome: outcome.Outcome(), } if sessionID != "" { resp.Raw = map[string]any{"session_id": sessionID} } - if outcome != nil { + if outcome.Outcome() != nil { return resp, nil } if req.Prompt.Schema != nil { @@ -492,8 +487,11 @@ func (p *Provider) initializeParams(req ai.Request) (initializeParams, error) { } approvalMode := "auto" + disallowed := tools.DenyList() if brokered { approvalMode = "ask" + } else { + disallowed = append(disallowed, "AskUserQuestion") } resume := req.SessionID @@ -514,9 +512,9 @@ func (p *Provider) initializeParams(req ai.Request) (initializeParams, error) { Model: bridgeModel(p.model), Effort: req.Effort, SystemPrompt: req.Prompt.System, - AppendSystemPrompt: req.Prompt.AppendSystem, + AppendSystemPrompt: strings.Join([]string{req.Prompt.AppendSystem, ai.QuestionInstructions("AskUserQuestion", brokered && tools["AskUserQuestion"] != api.ToolPolicyDeny)}, "\n\n"), AllowedTools: allowed, - DisallowedTools: tools.DenyList(), + DisallowedTools: disallowed, AdditionalDirs: req.Permissions.CleanDirectories(), MaxTurns: req.Budget.MaxTurns, MaxBudgetUsd: maxBudget, diff --git a/pkg/ai/provider/claudeagent/provider_test.go b/pkg/ai/provider/claudeagent/provider_test.go index dbeef3c1..a97644c3 100644 --- a/pkg/ai/provider/claudeagent/provider_test.go +++ b/pkg/ai/provider/claudeagent/provider_test.go @@ -69,7 +69,7 @@ func TestProvider_InitializeParamsTranslatesPortableToolNames(t *testing.T) { "NotATool": api.ToolPolicyDeny, }}}) require.NoError(t, err) - assert.Equal(t, []string{"Bash", "BashOutput", "Edit", "KillShell", "Monitor", "MultiEdit", "NotebookEdit"}, params.DisallowedTools) + assert.Equal(t, []string{"Bash", "BashOutput", "Edit", "KillShell", "Monitor", "MultiEdit", "NotebookEdit", "AskUserQuestion"}, params.DisallowedTools) assert.Equal(t, []string{"Read"}, params.AllowedTools) assert.Contains(t, logs.String(), `permissions.tools "NotATool" deny is ignored: anthropic agent has no tool it names`) } diff --git a/pkg/ai/provider/coalesce.go b/pkg/ai/provider/coalesce.go index 527eb64f..77f58ebc 100644 --- a/pkg/ai/provider/coalesce.go +++ b/pkg/ai/provider/coalesce.go @@ -25,7 +25,7 @@ func CoalesceStreamForRuntime(ctx context.Context, runtime ai.Runtime, model str lastResult *ai.Event errEvents []ai.Event sessionID string - outcome *ai.TerminalOutcome + outcome ai.TerminalOutcomeTracker outcomeErr error ) @@ -43,17 +43,12 @@ func CoalesceStreamForRuntime(ctx context.Context, runtime ai.Runtime, model str } resp, err := finaliseCoalescedResponse(runtime, model, text.String(), usage, lastResult, errEvents, sessionID, start) if resp != nil { - resp.TerminalOutcome = outcome + resp.TerminalOutcome = outcome.Outcome() } return resp, err } if outcomeErr == nil { - parsed, err := ai.TerminalOutcomeFromEvent(ev) - if err != nil { - outcomeErr = err - } else if parsed != nil { - outcome = parsed - } + outcomeErr = outcome.Observe(ev) } switch ev.Kind { case ai.EventText: diff --git a/pkg/ai/provider/codex_appserver.go b/pkg/ai/provider/codex_appserver.go index 6ff920e9..7f2ea841 100644 --- a/pkg/ai/provider/codex_appserver.go +++ b/pkg/ai/provider/codex_appserver.go @@ -5,6 +5,7 @@ import ( "encoding/json" "fmt" osexec "os/exec" + "strings" "sync" "time" @@ -148,6 +149,7 @@ func (c *CodexAppServer) ExecuteStream(ctx context.Context, req ai.Request) (<-c return nil, err } req = c.beginTurn(req) + req.Prompt.AppendSystem = strings.Join([]string{req.Prompt.AppendSystem, ai.QuestionInstructions("request_user_input", c.cfg.OnApproval != nil && req.Permissions.Mode == api.PermissionPlan)}, "\n\n") if err := c.ensureStarted(ctx); err != nil { c.turnMu.Unlock() return nil, err diff --git a/pkg/ai/provider/codex_appserver_process.go b/pkg/ai/provider/codex_appserver_process.go index 5b489137..33495915 100644 --- a/pkg/ai/provider/codex_appserver_process.go +++ b/pkg/ai/provider/codex_appserver_process.go @@ -9,7 +9,8 @@ import ( ) func newCodexAppServerProcess(cfg ai.Config) *exec.Process { - args := []string{"app-server"} + args := []string{"app-server", "-c", fmt.Sprintf("tools.experimental_request_user_input.enabled=%t", cfg.OnApproval != nil)} + args = append(args, "-c", "features.default_mode_request_user_input=false") if cfg.APIURL != "" { args = append(args, codexProviderOverride(cfg.APIURL)...) } diff --git a/pkg/ai/provider/codex_appserver_question.go b/pkg/ai/provider/codex_appserver_question.go index 614d03ef..3d44052f 100644 --- a/pkg/ai/provider/codex_appserver_question.go +++ b/pkg/ai/provider/codex_appserver_question.go @@ -100,9 +100,12 @@ func codexQuestionApproval(request codexUserInputRequest, raw json.RawMessage) ( if err != nil { return api.ApprovalRequest{}, fmt.Errorf("codex question input: %w", err) } - questions := make([]api.TerminalQuestion, 0, len(request.Questions)) + questions, err := api.TerminalQuestionsFromInput(input) + if err != nil { + return api.ApprovalRequest{}, fmt.Errorf("codex questions: %w", err) + } seen := make(map[string]struct{}, len(request.Questions)) - for _, question := range request.Questions { + for i, question := range request.Questions { if question.ID == "" || strings.TrimSpace(question.Question) == "" { return api.ApprovalRequest{}, fmt.Errorf("codex question request has an empty question id or text") } @@ -110,11 +113,8 @@ func codexQuestionApproval(request codexUserInputRequest, raw json.RawMessage) ( return api.ApprovalRequest{}, fmt.Errorf("codex question request repeats id %q", question.ID) } seen[question.ID] = struct{}{} - // MultiSelect: Codex takes a list of answers per question whatever the - // question was, so every one of them accepts several. - questions = append(questions, api.TerminalQuestion{ - ID: question.ID, Text: strings.TrimSpace(question.Question), MultiSelect: true, Secret: question.IsSecret, - }) + questions[i].Secret = question.IsSecret + questions[i].MultiSelect = len(questions[i].Options) == 0 } return api.ApprovalRequest{ Tool: "AskUserQuestion", Input: input, ToolUseID: request.ItemID, SessionID: request.ThreadID, diff --git a/pkg/ai/provider/codex_appserver_test.go b/pkg/ai/provider/codex_appserver_test.go index 5a8afdf4..619a16bb 100644 --- a/pkg/ai/provider/codex_appserver_test.go +++ b/pkg/ai/provider/codex_appserver_test.go @@ -30,6 +30,8 @@ func TestCodexAppServerProcessHonoursAPIURL(t *testing.T) { assert.Equal(t, "codex", process.Cmd) assert.Equal(t, []string{ "app-server", + "-c", "tools.experimental_request_user_input.enabled=false", + "-c", "features.default_mode_request_user_input=false", "-c", "model_provider=captain", "-c", "model_providers.captain.name=captain", "-c", "model_providers.captain.base_url=http://127.0.0.1:4020/v1", diff --git a/pkg/ai/question_policy.go b/pkg/ai/question_policy.go new file mode 100644 index 00000000..6e4484ff --- /dev/null +++ b/pkg/ai/question_policy.go @@ -0,0 +1,11 @@ +package ai + +import "fmt" + +// QuestionInstructions describes the answer channel the host actually provides. +func QuestionInstructions(tool string, available bool) string { + if available { + return fmt.Sprintf("When clarification is required, use %s and wait for the answer before continuing. Do not ask clarification questions in your final response or end the turn while waiting for an answer.", tool) + } + return "Do not ask clarification questions. This run cannot receive answers through a native question tool. Complete the requested work independently using the available evidence and authorized scope. If a required decision cannot be resolved, report the blocker in your final response instead of asking a question or claiming completion." +} diff --git a/pkg/ai/terminal_outcome_tracker.go b/pkg/ai/terminal_outcome_tracker.go new file mode 100644 index 00000000..4a416ff0 --- /dev/null +++ b/pkg/ai/terminal_outcome_tracker.go @@ -0,0 +1,47 @@ +package ai + +import "slices" + +// TerminalOutcomeTracker retains native questions only until their matching +// result arrives. Plan capture remains terminal even when ExitPlanMode is denied. +type TerminalOutcomeTracker struct { + plan *TerminalOutcome + questions []pendingQuestion +} + +type pendingQuestion struct { + id string + outcome *TerminalOutcome +} + +func (t *TerminalOutcomeTracker) Observe(event Event) error { + if event.ParentToolCallID != "" { + return nil + } + if event.ToolCallID != "" && (event.Kind == EventToolResult || event.Kind == EventToolUse) { + t.questions = slices.DeleteFunc(t.questions, func(q pendingQuestion) bool { return q.id == event.ToolCallID }) + } + outcome, err := TerminalOutcomeFromEvent(event) + if err != nil { + return err + } + if outcome != nil { + if outcome.Kind == TerminalOutcomeQuestions { + t.questions = append(t.questions, pendingQuestion{id: event.ToolCallID, outcome: outcome}) + } else { + t.plan = outcome + } + } + return nil +} + +func (t *TerminalOutcomeTracker) Outcome() *TerminalOutcome { + if len(t.questions) == 0 { + return t.plan + } + outcome := &TerminalOutcome{Kind: TerminalOutcomeQuestions} + for _, pending := range t.questions { + outcome.Questions = append(outcome.Questions, pending.outcome.Questions...) + } + return outcome +} diff --git a/pkg/cli/ai.go b/pkg/cli/ai.go index 453a89d8..31612013 100644 --- a/pkg/cli/ai.go +++ b/pkg/cli/ai.go @@ -195,6 +195,7 @@ func runBuffered(ctx context.Context, p ai.Provider, req ai.Request) (any, error } return AIPromptResult{ Text: text, + TerminalOutcome: resp.TerminalOutcome, StructuredOutput: structuredOutput, Model: model, Provider: runtime.Provider, @@ -223,8 +224,14 @@ func runStreaming(ctx context.Context, sp ai.StreamingProvider, req ai.Request) session = req.SessionID structuredOutput map[string]any structuredErr error + terminal ai.TerminalOutcomeTracker + terminalErr error ) - renderer := NewEventRenderer(os.Stderr) + renderer := promptEventRenderer(ctx) + ownRenderer := renderer == nil + if ownRenderer { + renderer = NewEventRenderer(os.Stderr) + } loop, err := ai.RunUntil(ctx, ai.LoopOptions{ Provider: sp, MaxIterations: 1, @@ -236,6 +243,9 @@ func runStreaming(ctx context.Context, sp ai.StreamingProvider, req ai.Request) return req, true }, OnEvent: func(iteration int, ev ai.Event) { + if terminalErr == nil { + terminalErr = terminal.Observe(ev) + } if ev.Model != "" { model = ev.Model } @@ -258,8 +268,8 @@ func runStreaming(ctx context.Context, sp ai.StreamingProvider, req ai.Request) } }, }) - if renderErr := renderer.Flush(); renderErr != nil { - return nil, errors.Join(err, renderErr) + if ownRenderer { + err = errors.Join(err, renderer.Flush()) } if err != nil { return nil, err @@ -267,6 +277,9 @@ func runStreaming(ctx context.Context, sp ai.StreamingProvider, req ai.Request) if structuredErr != nil { return nil, structuredErr } + if terminalErr != nil { + return nil, fmt.Errorf("invalid terminal outcome: %w", terminalErr) + } if loop.StopReason == "error" { return nil, fmt.Errorf("streaming loop stopped: %s", loop.StopReason) } @@ -289,6 +302,7 @@ func runStreaming(ctx context.Context, sp ai.StreamingProvider, req ai.Request) HistoryFile: historyFileForRun(providerOf(runtime), runtime.Mode, input.SessionID, dir), Input: input, InputTokens: usage.InputTokens, + TerminalOutcome: terminal.Outcome(), Output: usage.OutputTokens, CostUSD: cost, Duration: time.Since(start).Round(time.Millisecond).String(), diff --git a/pkg/cli/ai_options.go b/pkg/cli/ai_options.go index bdc038b7..4052f5c7 100644 --- a/pkg/cli/ai_options.go +++ b/pkg/cli/ai_options.go @@ -172,4 +172,6 @@ type AIPromptResult struct { Output int `json:"outputTokens" pretty:"label=Output Tokens"` CostUSD float64 `json:"costUSD,omitempty" pretty:"label=Cost USD"` Duration string `json:"duration" pretty:"label=Duration"` + + TerminalOutcome *ai.TerminalOutcome `json:"-" pretty:"-"` } diff --git a/pkg/cli/prompt_run.go b/pkg/cli/prompt_run.go index 4a9adce4..e2f00909 100644 --- a/pkg/cli/prompt_run.go +++ b/pkg/cli/prompt_run.go @@ -152,16 +152,26 @@ func executeSyncRun(ctx context.Context, rendered PromptRenderResult, opts AIPro return executeSyncRunSingle(ctx, rendered, opts) } -func executeSyncRunSingle(ctx context.Context, rendered PromptRenderResult, opts AIPromptOptions) (PromptRunResult, error) { - group := task.StartGroup[PromptRunResult]( - "prompt "+rendered.Name, +func executeSyncRunSingle(ctx context.Context, rendered PromptRenderResult, opts AIPromptOptions) (result PromptRunResult, err error) { + ctx, renderer, err := attachPromptTerminal(ctx, &rendered) + if err != nil { + return PromptRunResult{}, err + } + if renderer != nil { + defer func() { err = errors.Join(err, renderer.Flush()) }() + } + groupOptions := []task.TaskGroupOption{ task.WithKind("prompt"), task.WithLabels(promptTaskLabels(rendered, "")), - ) + } + if renderer != nil { + groupOptions = append(groupOptions, task.WithNoRender()) + } + group := task.StartGroup[PromptRunResult]("prompt "+rendered.Name, groupOptions...) run := group.Add("execute "+rendered.Mode+":"+rendered.Model, func(_ flanksourceContext.Context, t *task.Task) (PromptRunResult, error) { taskCtx := ai.ContextWithLogger(t.Context(), t) return executeSyncRunSingleDirect(taskCtx, t, rendered, opts, nil) - }, task.WithModel(rendered.Model), task.WithPrompt(rendered.Input.Prompt.User)) + }, task.WithContext(ctx), task.WithModel(rendered.Model), task.WithPrompt(rendered.Input.Prompt.User)) return run.GetResult() } @@ -175,6 +185,9 @@ func executeSyncRunSingleDirect(ctx context.Context, t *task.Task, rendered Prom return executeSyncWorkflowRun(t, rendered, opts.NoStream, binding) } r, err := executeDirectPrompt(ctx, rendered, opts) + if err == nil { + err = unansweredPromptQuestions(r.TerminalOutcome) + } recording := promptRecordingInput{Rendered: rendered, Binding: binding} if recordErr := recordCompletedRun(ctx, recording, directRun(rendered, r, err)); err != nil || recordErr != nil { return PromptRunResult{}, errors.Join(err, recordErr) diff --git a/pkg/cli/prompt_run_live.go b/pkg/cli/prompt_run_live.go index bc0f15aa..97133ae0 100644 --- a/pkg/cli/prompt_run_live.go +++ b/pkg/cli/prompt_run_live.go @@ -44,10 +44,17 @@ func runPromptWorkflow(t *task.Task, rendered PromptRenderResult, timeout time.D start := time.Now() acc := newPromptEventAccumulator(stream.publish, t, rendered.Model, rendered.Mode) acc.cwd, acc.idPrefix, acc.verify, acc.session = req.Cwd(), runID, stream.setVerify, stream.setRunMetadata + onEvent := acc.handle + if renderer := promptEventRenderer(ctx); renderer != nil && !noStream { + onEvent = func(iteration int, event ai.Event) { + acc.handle(iteration, event) + renderer.Handle(iteration, event) + } + } result, err := promptrun.Run(ctx, promptrun.Input{ Resolved: promptResolution(rendered, req), Config: rendered.Config, - OnEvent: acc.handle, + OnEvent: onEvent, Timeout: timeout, NoStream: noStream, Record: rec, @@ -97,6 +104,11 @@ func completedRunSummary(runID string, rendered PromptRenderResult, result promp if err != nil { return PromptRunSummary{}, err } + questionErr := unansweredPromptQuestions(result.Response.TerminalOutcome) + failure := promptrun.FailureReason(result.Verdicts) + if questionErr != nil { + failure = questionErr.Error() + } text, err := structuredOutputText(result.Response.Text, structured) if err != nil { return PromptRunSummary{}, err @@ -115,10 +127,10 @@ func completedRunSummary(runID string, rendered PromptRenderResult, result promp OutputTokens: result.Usage.OutputTokens, CostUSD: result.CostUSD, Duration: elapsed.Round(time.Millisecond).String(), - Success: result.Passed, + Success: result.Passed && questionErr == nil, Text: text, StructuredOutput: structured, - Error: promptrun.FailureReason(result.Verdicts), + Error: failure, }, nil } diff --git a/pkg/cli/prompt_run_terminal.go b/pkg/cli/prompt_run_terminal.go new file mode 100644 index 00000000..b8efed5f --- /dev/null +++ b/pkg/cli/prompt_run_terminal.go @@ -0,0 +1,43 @@ +package cli + +import ( + "context" + "fmt" + "os" + + "github.com/flanksource/captain/pkg/ai" + "github.com/flanksource/captain/pkg/ai/approval" + "golang.org/x/term" +) + +type promptRendererKey struct{} + +func attachPromptTerminal(ctx context.Context, rendered *PromptRenderResult) (context.Context, *EventRenderer, error) { + if rendered.Config.OnApproval != nil || rendered.Mode != "agent" || + (rendered.Provider != "anthropic" && rendered.Provider != "openai") || + (rendered.Provider == "anthropic" && rendered.Input.Permissions.Mode == "bypassPermissions") || + !term.IsTerminal(int(os.Stdin.Fd())) || !term.IsTerminal(int(os.Stderr.Fd())) { + return ctx, nil, nil + } + renderer := NewEventRenderer(os.Stderr) + terminal, err := approval.NewTerminal(approval.TerminalOptions{ + In: os.Stdin, Out: os.Stderr, Suspend: renderer.Suspend, + }) + if err != nil { + return ctx, nil, err + } + rendered.Config.OnApproval = terminal.OnApproval + return context.WithValue(ctx, promptRendererKey{}, renderer), renderer, nil +} + +func promptEventRenderer(ctx context.Context) *EventRenderer { + renderer, _ := ctx.Value(promptRendererKey{}).(*EventRenderer) + return renderer +} + +func unansweredPromptQuestions(outcome *ai.TerminalOutcome) error { + if outcome != nil && outcome.Kind == ai.TerminalOutcomeQuestions { + return fmt.Errorf("prompt ended with %d unanswered native questions", len(outcome.Questions)) + } + return nil +} diff --git a/pkg/cli/testdata/prompt-questions/README.md b/pkg/cli/testdata/prompt-questions/README.md new file mode 100644 index 00000000..c8e92115 --- /dev/null +++ b/pkg/cli/testdata/prompt-questions/README.md @@ -0,0 +1,29 @@ +# Prompt question regressions + +These fixtures exercise the real Claude Agent SDK and Codex app-server bridges through `captain prompt run`, with every model response supplied by `captain ai mock`. They cover terminal question routing, answer delivery, and the no-question policy without Ginkgo. + +Run from the repository root: + +```sh +make build +gavel fixtures outline 'pkg/cli/testdata/prompt-questions/*.fixture.yaml' +gavel fixtures --max-retries 0 --json 'pkg/cli/testdata/prompt-questions/*.fixture.yaml' +``` + +Dependencies: Gavel with YAML services and scripted PTY input, Node/npm, the Claude Agent SDK runtime, Codex CLI, jq, and psql for the workflow recording assertion. The workflow fixture provisions an isolated commons-db test database and applies Captain's migration bundle. It never uses the monitored session database. + +Each document starts its own strict loopback mock on an allocated port and creates a workspace, Claude configuration directory, and request journal under `.tmp/prompt-questions-.*`. Mock services are reaped by Gavel; workspace evidence remains available after a failure. Every case disables Captain monitoring hooks, and cases outside the workflow fixture also disable session recording. + +| Fixture | Regression | +| --- | --- | +| `streamed.fixture.yaml` | A native question reaches the terminal broker and the selected answer reaches the model. | +| `buffered.fixture.yaml` | `--no-stream` still permits questions. | +| `codex.fixture.yaml` | Codex plan mode asks through the broker, while a run without a terminal disables its question tool. | +| `redirected-stdout.fixture.yaml` | Questions use stderr while stdout remains a JSON command result. | +| `noninteractive.fixture.yaml` | Piped input removes native questions and supplies an explicit no-question instruction. | +| `terminal-policy.fixture.yaml` | Redirected stderr and explicit Claude bypass both disable questions without changing permission mode. | +| `workflow.fixture.yaml` | Workflow execution asks, resumes, verifies, and records the run as succeeded. | + +The scripted question offers both postgres and sqlite. The journal assertion checks the exact question-to-answer mapping in the tool result, so sqlite appearing among the original options is insufficient. The noninteractive assertion checks the advertised tools and system instructions sent to the mock; its scripted final reply alone is not evidence of policy enforcement. + +A missing terminal form is a regression even if the mock subsequently supplies a final response to the tool's error. Missing dependencies, mock request misses, and database startup errors are harness failures and must be reported separately. diff --git a/pkg/cli/testdata/prompt-questions/buffered.fixture.yaml b/pkg/cli/testdata/prompt-questions/buffered.fixture.yaml new file mode 100644 index 00000000..c5649de1 --- /dev/null +++ b/pkg/cli/testdata/prompt-questions/buffered.fixture.yaml @@ -0,0 +1,56 @@ +kind: Fixture +name: Captain buffered prompt answers a native question at the terminal +defaults: + timeout: 90s +env: + CAPTAIN_SESSION_DB_URL: "off" + CAPTAIN_MONITOR_HOOKS: "off" + CAPTAIN_DB_CONTEXT: default + ANTHROPIC_API_KEY: captain-mock + ANTHROPIC_AUTH_TOKEN: captain-mock + CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1" +steps: + - id: workspace + kind: exec + script: | + set -eu + mkdir -p "{{.fixture.dir}}/../../../../.tmp" + mktemp -d "{{.fixture.dir}}/../../../../.tmp/prompt-questions-buffered.XXXXXX" | tr -d '\n' + export: + CASE_DIR: "{{.outputs.stdout}}" + CAPTAIN_BIN: "{{.fixture.dir}}/../../../../.bin/captain" + override: true + - id: stack + kind: services + services: + aimock: + exec: '"$CAPTAIN_BIN" ai mock --only anthropic --addr 127.0.0.1:{{.port}} --scenario "{{.fixture.dir}}/question.aimock.yaml" --journal "$CASE_DIR/requests.jsonl"' + ready: {tcp: "127.0.0.1:{{.port}}"} + - id: ask + kind: exec + terminal: pty + cwd: "{{.env.CASE_DIR}}" + script: | + set -eu + "$CAPTAIN_BIN" prompt run --model agent:haiku --edit --sandbox off --budget 0 --max-tokens 4096 --timeout 45s --no-user --no-project --no-memory --no-skills --no-hooks --no-mcp --no-stream -p 'captain-question-fixture: ask which database the store should use, then acknowledge the answer.' + env: + ANTHROPIC_BASE_URL: "{{.env.AIMOCK_URL}}" + CLAUDE_CONFIG_DIR: "{{.env.CASE_DIR}}/claude" + input: + - {expect: "Question from the agent"} + - {expect: "Other (type an answer)", keys: [down, enter]} + cel: exitCode == 0 && stdout.contains("Which database should the store use?") && stdout.contains("CAPTAIN_QUESTION_COMPLETE") + - id: answer-reached-model + kind: exec + script: | + jq -s ' + [.[] | select(.path == "/v1/messages") | .request] as $requests | + { + advertised: any($requests[]; (.toolNames | index("AskUserQuestion")) != null), + nativeQuestionPolicy: any($requests[]; .system | contains("use AskUserQuestion and wait for the answer")), + answered: any($requests[].messages[]?; + ((.toolResults // []) | index("AskUserQuestion")) != null and + (.content | contains("\"Which database should the store use?\"=\"sqlite\""))) + } + ' "$CASE_DIR/requests.jsonl" + cel: json.advertised && json.nativeQuestionPolicy && json.answered diff --git a/pkg/cli/testdata/prompt-questions/codex.aimock.yaml b/pkg/cli/testdata/prompt-questions/codex.aimock.yaml new file mode 100644 index 00000000..3f2fc000 --- /dev/null +++ b/pkg/cli/testdata/prompt-questions/codex.aimock.yaml @@ -0,0 +1,42 @@ +name: captain-codex-prompt-question +openai: + - match: + prompt_contains: captain-codex-policy-fixture + respond: + function_call: + name: request_user_input + call_id: call_captain_disabled_question + arguments: + questions: + - id: storage + header: Storage + question: Which database should the store use? + options: + - label: postgres + description: Use the server database. + - label: sqlite + description: Use the embedded database. + - match: + tool_result_for: request_user_input + respond: + text: CAPTAIN_POLICY_COMPLETE + - match: + prompt_contains: captain-codex-question-fixture + respond: + function_call: + name: request_user_input + call_id: call_captain_question + arguments: + questions: + - id: storage + header: Storage + question: Which database should the store use? + options: + - label: postgres + description: Use the server database. + - label: sqlite + description: Use the embedded database. + - match: + tool_result_for: request_user_input + respond: + text: CAPTAIN_QUESTION_COMPLETE diff --git a/pkg/cli/testdata/prompt-questions/codex.fixture.yaml b/pkg/cli/testdata/prompt-questions/codex.fixture.yaml new file mode 100644 index 00000000..6f16368f --- /dev/null +++ b/pkg/cli/testdata/prompt-questions/codex.fixture.yaml @@ -0,0 +1,75 @@ +kind: Fixture +name: Captain Codex plan mode routes terminal questions and disables them without an answer channel +defaults: + timeout: 90s +env: + CAPTAIN_SESSION_DB_URL: "off" + CAPTAIN_MONITOR_HOOKS: "off" + CAPTAIN_DB_CONTEXT: default + OPENAI_API_KEY: captain-mock +steps: + - id: workspace + kind: exec + script: | + set -eu + mkdir -p "{{.fixture.dir}}/../../../../.tmp" + mktemp -d "{{.fixture.dir}}/../../../../.tmp/prompt-questions-codex.XXXXXX" | tr -d '\n' + export: + CASE_DIR: "{{.outputs.stdout}}" + CAPTAIN_BIN: "{{.fixture.dir}}/../../../../.bin/captain" + override: true + - id: stack + kind: services + services: + aimock: + exec: '"$CAPTAIN_BIN" ai mock --only openai --openai-addr 127.0.0.1:{{.port}} --scenario "{{.fixture.dir}}/codex.aimock.yaml" --journal "$CASE_DIR/requests.jsonl"' + ready: {tcp: "127.0.0.1:{{.port}}"} + - id: noninteractive + kind: exec + cwd: "{{.env.CASE_DIR}}" + script: | + set -eu + mkdir -p "$CODEX_HOME" + "$CAPTAIN_BIN" prompt run --model agent:sol --mode agent --api-url "{{.env.AIMOCK_URL}}/v1" --api-key captain-mock --permission-mode plan --sandbox native --budget 0 --timeout 45s --no-user --no-project --no-memory --no-skills --no-hooks --no-mcp --json -p 'captain-codex-policy-fixture: finish with the available information.' > "$CASE_DIR/policy-result.json" + jq -s --slurpfile result "$CASE_DIR/policy-result.json" ' + [.[] | select(.path == "/v1/responses") | .request] as $requests | + { + completed: ($result[0].status == "completed" and $result[0].mode == "agent" and $result[0].text == "CAPTAIN_POLICY_COMPLETE"), + requests: ($requests | length), + questionBlocked: any($requests[].messages[]? | + select(((.toolResults // []) | index("request_user_input")) != null); + (.content | test("(?i)(unavailable|not available|unknown|unrecognized|unsupported|disabled)"))), + policyPresent: any($requests[].messages[]?; (.content // "") | contains("Do not ask clarification questions.")) + } + ' "$CASE_DIR/requests.jsonl" + env: + CODEX_HOME: "{{.env.CASE_DIR}}/codex-policy" + cel: json.requests > 0 && json.completed && json.questionBlocked && json.policyPresent + - id: ask + kind: exec + terminal: pty + cwd: "{{.env.CASE_DIR}}" + script: | + set -eu + mkdir -p "$CODEX_HOME" + "$CAPTAIN_BIN" prompt run --model agent:sol --mode agent --api-url "{{.env.AIMOCK_URL}}/v1" --api-key captain-mock --permission-mode plan --sandbox native --budget 0 --timeout 45s --no-user --no-project --no-memory --no-skills --no-hooks --no-mcp -p 'captain-codex-question-fixture: ask which database the store should use, then acknowledge the answer.' + env: + CODEX_HOME: "{{.env.CASE_DIR}}/codex-question" + input: + - {expect: "Question from the agent"} + - {expect: "Other (type an answer)", keys: [down, enter]} + cel: exitCode == 0 && stdout.contains("Which database should the store use?") && stdout.contains("CAPTAIN_QUESTION_COMPLETE") + - id: answer-reached-model + kind: exec + script: | + jq -s ' + [.[] | select(.path == "/v1/responses") | .request | + select(any(.messages[]?; (.content // "") | contains("captain-codex-question-fixture")))] as $requests | + { + nativeQuestionPolicy: any($requests[].messages[]?; (.content // "") | contains("use request_user_input and wait for the answer")), + answered: any($requests[].messages[]? | + select(((.toolResults // []) | index("request_user_input")) != null); + ((.content | fromjson).answers.storage.answers == ["sqlite"])) + } + ' "$CASE_DIR/requests.jsonl" + cel: json.nativeQuestionPolicy && json.answered diff --git a/pkg/cli/testdata/prompt-questions/noninteractive.fixture.yaml b/pkg/cli/testdata/prompt-questions/noninteractive.fixture.yaml new file mode 100644 index 00000000..a25a9f97 --- /dev/null +++ b/pkg/cli/testdata/prompt-questions/noninteractive.fixture.yaml @@ -0,0 +1,49 @@ +kind: Fixture +name: Captain without a terminal disables native questions and supplies a no-question policy +defaults: + timeout: 90s +env: + CAPTAIN_SESSION_DB_URL: "off" + CAPTAIN_MONITOR_HOOKS: "off" + CAPTAIN_DB_CONTEXT: default + ANTHROPIC_API_KEY: captain-mock + ANTHROPIC_AUTH_TOKEN: captain-mock + CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1" +steps: + - id: workspace + kind: exec + script: | + set -eu + mkdir -p "{{.fixture.dir}}/../../../../.tmp" + mktemp -d "{{.fixture.dir}}/../../../../.tmp/prompt-questions-noninteractive.XXXXXX" | tr -d '\n' + export: + CASE_DIR: "{{.outputs.stdout}}" + CAPTAIN_BIN: "{{.fixture.dir}}/../../../../.bin/captain" + override: true + - id: stack + kind: services + services: + aimock: + exec: '"$CAPTAIN_BIN" ai mock --only anthropic --addr 127.0.0.1:{{.port}} --scenario "{{.fixture.dir}}/policy.aimock.yaml" --journal "$CASE_DIR/requests.jsonl"' + ready: {tcp: "127.0.0.1:{{.port}}"} + - id: no-question-policy + kind: exec + cwd: "{{.env.CASE_DIR}}" + script: | + set -eu + printf '%s' 'captain-question-policy-fixture: finish with the available information.' | + "$CAPTAIN_BIN" prompt run --model agent:haiku --edit --sandbox off --budget 0 --max-tokens 4096 --timeout 45s --no-user --no-project --no-memory --no-skills --no-hooks --no-mcp --json > "$CASE_DIR/result.json" + jq -s --slurpfile result "$CASE_DIR/result.json" ' + [.[] | select(.path == "/v1/messages") | .request | + select(any(.messages[]?; .role == "user" and (.content | contains("captain-question-policy-fixture"))))] as $requests | + { + requests: ($requests | length), + completed: ($result[0].status == "completed" and $result[0].text == "CAPTAIN_POLICY_COMPLETE"), + questionsAdvertised: any($requests[]; (.toolNames | index("AskUserQuestion")) != null), + noQuestionPolicy: any($requests[]; .system | test("(?i)(do not|must not|never) ask (the user |any |clarifying |clarification )?questions")) + } + ' "$CASE_DIR/requests.jsonl" + env: + ANTHROPIC_BASE_URL: "{{.env.AIMOCK_URL}}" + CLAUDE_CONFIG_DIR: "{{.env.CASE_DIR}}/claude" + cel: json.requests > 0 && json.completed && !json.questionsAdvertised && json.noQuestionPolicy diff --git a/pkg/cli/testdata/prompt-questions/policy.aimock.yaml b/pkg/cli/testdata/prompt-questions/policy.aimock.yaml new file mode 100644 index 00000000..89f38446 --- /dev/null +++ b/pkg/cli/testdata/prompt-questions/policy.aimock.yaml @@ -0,0 +1,15 @@ +name: captain-prompt-question-policy +description: The fixture checks the actual request policy and tool list, independently of this final reply. +anthropic: + - match: + system_contains: You are naming a coding session + repeat: -1 + respond: + text: Captain policy fixture + stop_reason: end_turn + - match: + prompt_contains: captain-question-policy-fixture + repeat: -1 + respond: + text: CAPTAIN_POLICY_COMPLETE + stop_reason: end_turn diff --git a/pkg/cli/testdata/prompt-questions/question.aimock.yaml b/pkg/cli/testdata/prompt-questions/question.aimock.yaml new file mode 100644 index 00000000..25507758 --- /dev/null +++ b/pkg/cli/testdata/prompt-questions/question.aimock.yaml @@ -0,0 +1,31 @@ +name: captain-prompt-question +description: Native question followed by a reply to its tool result; no unmatched-request fallback. +anthropic: + - match: + system_contains: You are naming a coding session + repeat: -1 + respond: + text: Captain question fixture + stop_reason: end_turn + - match: + prompt_contains: captain-question-fixture + respond: + tool_use: + name: AskUserQuestion + id: toolu_captain_question + input: + questions: + - question: Which database should the store use? + header: Storage + options: + - label: postgres + description: Use the server database. + - label: sqlite + description: Use the embedded database. + multiSelect: false + stop_reason: tool_use + - match: + tool_result_for: AskUserQuestion + respond: + text: CAPTAIN_QUESTION_COMPLETE + stop_reason: end_turn diff --git a/pkg/cli/testdata/prompt-questions/redirected-stdout.fixture.yaml b/pkg/cli/testdata/prompt-questions/redirected-stdout.fixture.yaml new file mode 100644 index 00000000..1ce90711 --- /dev/null +++ b/pkg/cli/testdata/prompt-questions/redirected-stdout.fixture.yaml @@ -0,0 +1,61 @@ +kind: Fixture +name: Captain redirected-stdout prompt answers a native question at the terminal +defaults: + timeout: 90s +env: + CAPTAIN_SESSION_DB_URL: "off" + CAPTAIN_MONITOR_HOOKS: "off" + CAPTAIN_DB_CONTEXT: default + ANTHROPIC_API_KEY: captain-mock + ANTHROPIC_AUTH_TOKEN: captain-mock + CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1" +steps: + - id: workspace + kind: exec + script: | + set -eu + mkdir -p "{{.fixture.dir}}/../../../../.tmp" + mktemp -d "{{.fixture.dir}}/../../../../.tmp/prompt-questions-redirected-stdout.XXXXXX" | tr -d '\n' + export: + CASE_DIR: "{{.outputs.stdout}}" + CAPTAIN_BIN: "{{.fixture.dir}}/../../../../.bin/captain" + override: true + - id: stack + kind: services + services: + aimock: + exec: '"$CAPTAIN_BIN" ai mock --only anthropic --addr 127.0.0.1:{{.port}} --scenario "{{.fixture.dir}}/question.aimock.yaml" --journal "$CASE_DIR/requests.jsonl"' + ready: {tcp: "127.0.0.1:{{.port}}"} + - id: ask + kind: exec + terminal: pty + cwd: "{{.env.CASE_DIR}}" + script: | + set -eu + "$CAPTAIN_BIN" prompt run --model agent:haiku --edit --sandbox off --budget 0 --max-tokens 4096 --timeout 45s --no-user --no-project --no-memory --no-skills --no-hooks --no-mcp -p 'captain-question-fixture: ask which database the store should use, then acknowledge the answer.' --json > "$CASE_DIR/result.json" + env: + ANTHROPIC_BASE_URL: "{{.env.AIMOCK_URL}}" + CLAUDE_CONFIG_DIR: "{{.env.CASE_DIR}}/claude" + input: + - {expect: "Question from the agent"} + - {expect: "Other (type an answer)", keys: [down, enter]} + cel: exitCode == 0 && stdout.contains("Which database should the store use?") + - id: answer-reached-model + kind: exec + script: | + jq -s ' + [.[] | select(.path == "/v1/messages") | .request] as $requests | + { + advertised: any($requests[]; (.toolNames | index("AskUserQuestion")) != null), + nativeQuestionPolicy: any($requests[]; .system | contains("use AskUserQuestion and wait for the answer")), + answered: any($requests[].messages[]?; + ((.toolResults // []) | index("AskUserQuestion")) != null and + (.content | contains("\"Which database should the store use?\"=\"sqlite\""))) + } + ' "$CASE_DIR/requests.jsonl" + cel: json.advertised && json.nativeQuestionPolicy && json.answered + - id: stdout-remains-json + kind: exec + exec: jq + args: [".", "{{.env.CASE_DIR}}/result.json"] + cel: json.status == "completed" && json.text == "CAPTAIN_QUESTION_COMPLETE" diff --git a/pkg/cli/testdata/prompt-questions/streamed.fixture.yaml b/pkg/cli/testdata/prompt-questions/streamed.fixture.yaml new file mode 100644 index 00000000..5d515c0d --- /dev/null +++ b/pkg/cli/testdata/prompt-questions/streamed.fixture.yaml @@ -0,0 +1,56 @@ +kind: Fixture +name: Captain streamed prompt answers a native question at the terminal +defaults: + timeout: 90s +env: + CAPTAIN_SESSION_DB_URL: "off" + CAPTAIN_MONITOR_HOOKS: "off" + CAPTAIN_DB_CONTEXT: default + ANTHROPIC_API_KEY: captain-mock + ANTHROPIC_AUTH_TOKEN: captain-mock + CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1" +steps: + - id: workspace + kind: exec + script: | + set -eu + mkdir -p "{{.fixture.dir}}/../../../../.tmp" + mktemp -d "{{.fixture.dir}}/../../../../.tmp/prompt-questions-streamed.XXXXXX" | tr -d '\n' + export: + CASE_DIR: "{{.outputs.stdout}}" + CAPTAIN_BIN: "{{.fixture.dir}}/../../../../.bin/captain" + override: true + - id: stack + kind: services + services: + aimock: + exec: '"$CAPTAIN_BIN" ai mock --only anthropic --addr 127.0.0.1:{{.port}} --scenario "{{.fixture.dir}}/question.aimock.yaml" --journal "$CASE_DIR/requests.jsonl"' + ready: {tcp: "127.0.0.1:{{.port}}"} + - id: ask + kind: exec + terminal: pty + cwd: "{{.env.CASE_DIR}}" + script: | + set -eu + "$CAPTAIN_BIN" prompt run --model agent:haiku --edit --sandbox off --budget 0 --max-tokens 4096 --timeout 45s --no-user --no-project --no-memory --no-skills --no-hooks --no-mcp -p 'captain-question-fixture: ask which database the store should use, then acknowledge the answer.' + env: + ANTHROPIC_BASE_URL: "{{.env.AIMOCK_URL}}" + CLAUDE_CONFIG_DIR: "{{.env.CASE_DIR}}/claude" + input: + - {expect: "Question from the agent"} + - {expect: "Other (type an answer)", keys: [down, enter]} + cel: exitCode == 0 && stdout.contains("Which database should the store use?") && stdout.contains("CAPTAIN_QUESTION_COMPLETE") + - id: answer-reached-model + kind: exec + script: | + jq -s ' + [.[] | select(.path == "/v1/messages") | .request] as $requests | + { + advertised: any($requests[]; (.toolNames | index("AskUserQuestion")) != null), + nativeQuestionPolicy: any($requests[]; .system | contains("use AskUserQuestion and wait for the answer")), + answered: any($requests[].messages[]?; + ((.toolResults // []) | index("AskUserQuestion")) != null and + (.content | contains("\"Which database should the store use?\"=\"sqlite\""))) + } + ' "$CASE_DIR/requests.jsonl" + cel: json.advertised && json.nativeQuestionPolicy && json.answered diff --git a/pkg/cli/testdata/prompt-questions/terminal-policy.fixture.yaml b/pkg/cli/testdata/prompt-questions/terminal-policy.fixture.yaml new file mode 100644 index 00000000..e9574be1 --- /dev/null +++ b/pkg/cli/testdata/prompt-questions/terminal-policy.fixture.yaml @@ -0,0 +1,65 @@ +kind: Fixture +name: Captain disables questions when stderr is redirected or Claude bypasses permissions +defaults: + timeout: 90s +env: + CAPTAIN_SESSION_DB_URL: "off" + CAPTAIN_MONITOR_HOOKS: "off" + CAPTAIN_DB_CONTEXT: default + ANTHROPIC_API_KEY: captain-mock + ANTHROPIC_AUTH_TOKEN: captain-mock + CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1" +steps: + - id: workspace + kind: exec + script: | + set -eu + mkdir -p "{{.fixture.dir}}/../../../../.tmp" + mktemp -d "{{.fixture.dir}}/../../../../.tmp/prompt-questions-terminal-policy.XXXXXX" | tr -d '\n' + export: + CASE_DIR: "{{.outputs.stdout}}" + CAPTAIN_BIN: "{{.fixture.dir}}/../../../../.bin/captain" + override: true + - id: stack + kind: services + services: + aimock: + exec: '"$CAPTAIN_BIN" ai mock --only anthropic --addr 127.0.0.1:{{.port}} --scenario "{{.fixture.dir}}/policy.aimock.yaml" --journal "$CASE_DIR/requests.jsonl"' + ready: {tcp: "127.0.0.1:{{.port}}"} + - id: redirected-stderr + kind: exec + terminal: pty + cwd: "{{.env.CASE_DIR}}" + script: | + set -eu + "$CAPTAIN_BIN" prompt run --model agent:haiku --edit --sandbox off --budget 0 --max-tokens 4096 --timeout 45s --no-user --no-project --no-memory --no-skills --no-hooks --no-mcp --json -p 'captain-question-policy-fixture: redirected-stderr' > "$CASE_DIR/stderr-result.json" 2> "$CASE_DIR/stderr.log" + env: + ANTHROPIC_BASE_URL: "{{.env.AIMOCK_URL}}" + CLAUDE_CONFIG_DIR: "{{.env.CASE_DIR}}/claude-stderr" + cel: exitCode == 0 + - id: bypass + kind: exec + terminal: pty + cwd: "{{.env.CASE_DIR}}" + script: | + set -eu + "$CAPTAIN_BIN" prompt run --model agent:haiku --permission-mode bypassPermissions --sandbox off --budget 0 --max-tokens 4096 --timeout 45s --no-user --no-project --no-memory --no-skills --no-hooks --no-mcp --json -p 'captain-question-policy-fixture: bypass' > "$CASE_DIR/bypass-result.json" + env: + ANTHROPIC_BASE_URL: "{{.env.AIMOCK_URL}}" + CLAUDE_CONFIG_DIR: "{{.env.CASE_DIR}}/claude-bypass" + cel: exitCode == 0 + - id: policies-reached-model + kind: exec + script: | + jq -s --slurpfile stderrResult "$CASE_DIR/stderr-result.json" --slurpfile bypassResult "$CASE_DIR/bypass-result.json" ' + [.[] | select(.path == "/v1/messages") | .request | + select(any(.messages[]?; .role == "user" and (.content | contains("captain-question-policy-fixture"))))] as $requests | + { + stderrCompleted: ($stderrResult[0].status == "completed" and $stderrResult[0].text == "CAPTAIN_POLICY_COMPLETE"), + bypassCompleted: ($bypassResult[0].status == "completed" and $bypassResult[0].text == "CAPTAIN_POLICY_COMPLETE"), + requests: ($requests | length), + questionsAbsent: all($requests[]; (.toolNames | index("AskUserQuestion")) == null), + policiesPresent: all($requests[]; .system | contains("Do not ask clarification questions.")) + } + ' "$CASE_DIR/requests.jsonl" + cel: json.requests == 2 && json.stderrCompleted && json.bypassCompleted && json.questionsAbsent && json.policiesPresent diff --git a/pkg/cli/testdata/prompt-questions/workflow.fixture.yaml b/pkg/cli/testdata/prompt-questions/workflow.fixture.yaml new file mode 100644 index 00000000..46cd53b3 --- /dev/null +++ b/pkg/cli/testdata/prompt-questions/workflow.fixture.yaml @@ -0,0 +1,77 @@ +kind: Fixture +name: Captain workflow continues after a terminal question and records success +defaults: + timeout: 90s +env: + CAPTAIN_SESSION_DB_URL: "off" + CAPTAIN_MONITOR_HOOKS: "off" + CAPTAIN_DB_CONTEXT: default + ANTHROPIC_API_KEY: captain-mock + ANTHROPIC_AUTH_TOKEN: captain-mock + CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1" +steps: + - id: workspace + kind: exec + script: | + set -eu + mkdir -p "{{.fixture.dir}}/../../../../.tmp" + mktemp -d "{{.fixture.dir}}/../../../../.tmp/prompt-questions-workflow.XXXXXX" | tr -d '\n' + export: + CASE_DIR: "{{.outputs.stdout}}" + CAPTAIN_BIN: "{{.fixture.dir}}/../../../../.bin/captain" + override: true + - id: stack + kind: services + services: + database: + dbtest: + migrations: + dir: "{{.fixture.dir}}/../../../../migrations" + name: captain + aimock: + exec: '"$CAPTAIN_BIN" ai mock --only anthropic --addr 127.0.0.1:{{.port}} --scenario "{{.fixture.dir}}/question.aimock.yaml" --journal "$CASE_DIR/requests.jsonl"' + ready: {tcp: "127.0.0.1:{{.port}}"} + - id: ask + kind: exec + terminal: pty + cwd: "{{.env.CASE_DIR}}" + script: | + set -eu + "$CAPTAIN_BIN" prompt run "{{.fixture.dir}}/workflow.prompt" --model agent:haiku --edit --sandbox off --budget 0 --max-tokens 4096 --timeout 45s --no-user --no-project --no-memory --no-skills --no-hooks --no-mcp + env: + ANTHROPIC_BASE_URL: "{{.env.AIMOCK_URL}}" + CLAUDE_CONFIG_DIR: "{{.env.CASE_DIR}}/claude" + CAPTAIN_SESSION_DB_URL: "{{.steps.stack.database.url}}" + input: + - {expect: "Question from the agent"} + - {expect: "Other (type an answer)", keys: [down, enter]} + cel: exitCode == 0 && stdout.contains("CAPTAIN_QUESTION_COMPLETE") + - id: answer-reached-model + kind: exec + script: | + jq -s ' + [.[] | select(.path == "/v1/messages") | .request] as $requests | + { + advertised: any($requests[]; (.toolNames | index("AskUserQuestion")) != null), + nativeQuestionPolicy: any($requests[]; .system | contains("use AskUserQuestion and wait for the answer")), + answered: any($requests[].messages[]?; + ((.toolResults // []) | index("AskUserQuestion")) != null and + (.content | contains("\"Which database should the store use?\"=\"sqlite\""))) + } + ' "$CASE_DIR/requests.jsonl" + cel: json.advertised && json.nativeQuestionPolicy && json.answered + - id: verifier-ran + kind: exec + exec: jq + args: [-n, --rawfile, verified, "{{.env.CASE_DIR}}/question-verified.txt", '{verified: ($verified == "verified")}'] + cel: json.verified + - id: recorded-as-succeeded + kind: exec + exec: psql + args: + - "{{.steps.stack.database.url}}" + - -XAt + - --set=ON_ERROR_STOP=1 + - -c + - SELECT state::text FROM captain_prompt_runs WHERE result_text = 'CAPTAIN_QUESTION_COMPLETE' + cel: stdout.trim() == "succeeded" diff --git a/pkg/cli/testdata/prompt-questions/workflow.prompt b/pkg/cli/testdata/prompt-questions/workflow.prompt new file mode 100644 index 00000000..75eea682 --- /dev/null +++ b/pkg/cli/testdata/prompt-questions/workflow.prompt @@ -0,0 +1,12 @@ +--- +model: agent:haiku +permissions: + mode: acceptEdits + presets: [edit] +workflow: + verify: + commands: + - printf '%s' verified > question-verified.txt + maxIterations: 1 +--- +captain-question-fixture: ask which database the store should use, then acknowledge the answer. From 426d51737723359b5028ff0270ec4bcc334f6887 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Thu, 22 Oct 2026 11:20:44 +0300 Subject: [PATCH 04/77] feat: add promptfile lint command Claude-Session-Id: 01a161f3-946a-7f80-8de1-6443c175cde5 --- cmd/captain/lint.go | 56 ++++++ cmd/captain/lint_ginkgo_test.go | 85 +++++++++ cmd/captain/main.go | 1 + docs/src/pages/prompts/format.mdx | 24 +++ examples/lint-review.prompt | 9 + go.mod | 39 +++- go.sum | 166 ++++++++++++++--- pkg/ai/prompt/validate.go | 185 +++++++++++++++++++ pkg/ai/prompt/validate_ginkgo_test.go | 102 +++++++++++ pkg/ai/prompt/validate_schema.go | 84 +++++++++ pkg/ai/prompt/validate_variables.go | 243 +++++++++++++++++++++++++ pkg/cli/prompt_render.go | 2 +- pkg/cli/prompt_source.go | 7 +- pkg/lint/promptfile/run.go | 129 +++++++++++++ pkg/lint/promptfile/run_ginkgo_test.go | 106 +++++++++++ 15 files changed, 1203 insertions(+), 35 deletions(-) create mode 100644 cmd/captain/lint.go create mode 100644 cmd/captain/lint_ginkgo_test.go create mode 100644 examples/lint-review.prompt create mode 100644 pkg/ai/prompt/validate.go create mode 100644 pkg/ai/prompt/validate_ginkgo_test.go create mode 100644 pkg/ai/prompt/validate_schema.go create mode 100644 pkg/ai/prompt/validate_variables.go create mode 100644 pkg/lint/promptfile/run.go create mode 100644 pkg/lint/promptfile/run_ginkgo_test.go diff --git a/cmd/captain/lint.go b/cmd/captain/lint.go new file mode 100644 index 00000000..6e26569a --- /dev/null +++ b/cmd/captain/lint.go @@ -0,0 +1,56 @@ +package main + +import ( + "context" + "errors" + "io" + "os" + + "github.com/flanksource/captain/pkg/cli" + "github.com/flanksource/captain/pkg/lint/promptfile" + "github.com/flanksource/clicky" + "github.com/flanksource/gavel/linters" + "github.com/flanksource/gavel/models" + "github.com/spf13/cobra" +) + +type promptfileLintOptions struct { + Paths []string `args:"true" help:"Promptfiles or directories (default: current directory)"` + Var []string `flag:"var" short:"V" help:"Sample template input as key=value; repeat for multiple inputs"` + Vars string `flag:"vars" clicky:"cli-file-read" help:"Sample template inputs as a JSON object, or @file"` +} + +func registerLintCommand(root *cobra.Command) { + parent := &cobra.Command{Use: "lint", Short: "Validate Captain configuration files"} + clicky.MarkLocalOnly(parent) + root.AddCommand(parent) + command := clicky.AddNamedCommandWithContext("promptfile", parent, promptfileLintOptions{}, func(ctx context.Context, options promptfileLintOptions) ([]*linters.LinterResult, error) { + workDir, err := os.Getwd() + if err != nil { + return promptfileLintFailure(err) + } + var stdin []byte + if isStdinAvailable() { + stdin, err = io.ReadAll(os.Stdin) + if err != nil { + return promptfileLintFailure(err) + } + } + variables, err := cli.ParsePromptVariables(cli.AIPromptOptions{Var: options.Var}, options.Vars, string(stdin), false) + if err != nil { + return promptfileLintFailure(err) + } + results := promptfile.Run(ctx, promptfile.Options{WorkDir: workDir, Paths: options.Paths, Data: variables.Data}) + if results[0].Test().Sum().Failed > 0 { + return results, errors.New("promptfile lint failed") + } + return results, nil + }) + command.Use = "promptfile [paths...]" + command.Short = "Validate .prompt declarations and template syntax without running a model" + command.Long = "Validate .prompt files using Gavel's linter framework. Directory discovery respects Git ignore rules. Missing frontmatter inputs warn and defer declaration checks; use --var or --vars for full validation. Missing body variables are allowed. Warnings exit successfully; errors exit nonzero." +} + +func promptfileLintFailure(err error) ([]*linters.LinterResult, error) { + return []*linters.LinterResult{{Linter: "promptfile", Error: err.Error(), Violations: []models.Violation{}}}, err +} diff --git a/cmd/captain/lint_ginkgo_test.go b/cmd/captain/lint_ginkgo_test.go new file mode 100644 index 00000000..7f6f665b --- /dev/null +++ b/cmd/captain/lint_ginkgo_test.go @@ -0,0 +1,85 @@ +package main + +import ( + "encoding/json" + "os" + "path/filepath" + + "github.com/flanksource/clicky" + "github.com/flanksource/gavel/linters" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("Promptfile lint command", func() { + It("registers a local-only command with sample-input flags", func() { + command, _, err := newRootCommand().Find([]string{"lint", "promptfile"}) + Expect(err).NotTo(HaveOccurred()) + Expect(command.Name()).To(Equal("promptfile")) + Expect(clicky.IsLocalOnly(command)).To(BeTrue()) + Expect(command.Flags().Lookup("var")).NotTo(BeNil()) + Expect(command.Flags().Lookup("vars")).NotTo(BeNil()) + }) + + DescribeTable("emits Gavel JSON and applies the framework severity verdict", + func(source string, extra []string, fails bool, findings int) { + path := filepath.Join(GinkgoT().TempDir(), "review.prompt") + Expect(os.WriteFile(path, []byte(source), 0o600)).To(Succeed()) + output, err := capturePromptfileOutput(append([]string{"lint", "promptfile", path, "--format", "json"}, extra...)) + Expect(err != nil).To(Equal(fails), output) + var results []*linters.LinterResult + Expect(json.Unmarshal([]byte(output), &results)).To(Succeed(), output) + Expect(results).To(HaveLen(1)) + Expect(results[0].Linter).To(Equal("promptfile")) + Expect(results[0].FileCount).To(Equal(1)) + Expect(results[0].Violations).To(HaveLen(findings)) + }, + Entry("valid reusable prompt", "Review {{missing}}\n", nil, false, 0), + Entry("invalid YAML retains its finding", "---\nmodel: [unfinished\n---\nbody\n", nil, true, 1), + Entry("missing inputs warn", "---\nbudget:\n maxTokens: {{limit}}\n---\nbody\n", nil, false, 1), + Entry("JSON sample inputs", "---\nbudget:\n maxTokens: {{limit}}\n---\nbody\n", []string{"--vars", `{"limit": 100}`}, false, 0), + Entry("individual inputs override JSON", "---\nbudget:\n maxTokens: {{limit}}\n---\nbody\n", []string{"--vars", `{"limit": -1}`, "--var", "limit=100"}, false, 0), + Entry("rendered invalid option", "---\nbudget:\n maxTokens: {{limit}}\n---\nbody\n", []string{"--var", "limit=-1"}, true, 1), + ) + + DescribeTable("preserves structured failures for invalid inputs", + func(extra []string, message string) { + output, err := capturePromptfileOutput(append([]string{"lint", "promptfile", "--format", "json"}, extra...)) + Expect(err).To(HaveOccurred()) + var results []*linters.LinterResult + Expect(json.Unmarshal([]byte(output), &results)).To(Succeed(), output) + Expect(results).To(ConsistOf(And(HaveField("Success", false), HaveField("Error", ContainSubstring(message))))) + }, + Entry("missing file", []string{"missing-review.prompt"}, "missing-review.prompt"), + Entry("malformed JSON", []string{"--vars", "["}, "--vars"), + Entry("null JSON", []string{"--vars", "null", "--var", "limit=100"}, "object"), + Entry("malformed variable", []string{"--var", "limit"}, "key=value"), + ) + + It("renders actionable diagnostics in the human format", func() { + path := filepath.Join(GinkgoT().TempDir(), "review.prompt") + Expect(os.WriteFile(path, []byte("---\nmode: invalid\n---\nbody\n"), 0o600)).To(Succeed()) + output, err := capturePromptfileOutput([]string{"lint", "promptfile", path, "--format", "pretty", "--no-color"}) + Expect(err).To(HaveOccurred()) + Expect(output).To(ContainSubstring("review.prompt")) + Expect(output).To(ContainSubstring("mode")) + }) +}) + +func capturePromptfileOutput(args []string) (string, error) { + GinkgoHelper() + output, err := os.CreateTemp(GinkgoT().TempDir(), "stdout") + Expect(err).NotTo(HaveOccurred()) + previousStdout, previousFlags := os.Stdout, *clicky.Flags + defer func() { + os.Stdout, *clicky.Flags = previousStdout, previousFlags + Expect(output.Close()).To(Succeed()) + }() + os.Stdout = output + root := newRootCommand() + root.SetArgs(args) + err = root.Execute() + data, readErr := os.ReadFile(output.Name()) + Expect(readErr).NotTo(HaveOccurred()) + return string(data), err +} diff --git a/cmd/captain/main.go b/cmd/captain/main.go index a0c529f3..c2c19e2a 100644 --- a/cmd/captain/main.go +++ b/cmd/captain/main.go @@ -143,6 +143,7 @@ func newRootCommand() *cobra.Command { clicky.AddNamedCommandWithContext("tokens", sessionsCmd, cli.SessionTokensOptions{}, cli.RunSessionTokens).Short = "Size canonical transcript rows without changing recorded usage" rootCmd.AddCommand(cli.NewBrowserCommand()) + registerLintCommand(rootCmd) psCmd := clicky.AddNamedCommandWithContext("ps", rootCmd, cli.PSOptions{}, cli.RunPS) psCmd.Short = "List live agent sessions, or inspect specific process IDs" diff --git a/docs/src/pages/prompts/format.mdx b/docs/src/pages/prompts/format.mdx index f33653b3..649f02c7 100644 --- a/docs/src/pages/prompts/format.mdx +++ b/docs/src/pages/prompts/format.mdx @@ -196,3 +196,27 @@ Commit message: Patch: {{patch}} `} /> + +## Lint promptfiles + +Run `captain lint promptfile [paths...]` before executing a prompt. It checks frontmatter delimiters, YAML, Handlebars syntax, Captain declarations, structural options, hooks, and Picoschema, JSON Schema, or native TypeSafe output declarations. Validation does not execute the body, contact a model, resolve presets, or open a database. Body-only prompts and declarations that inherit their model remain valid. + + + +File arguments are checked directly, including explicitly named ignored files. Directory discovery respects Git ignore rules and skips nested projects. Overlapping paths are checked once. A missing path, unreadable file, or selection containing no `.prompt` files fails with an actionable error. + +Missing body variables are allowed because lint does not render the body. Frontmatter variables need values to validate the declarations they generate: without complete sample inputs, lint checks template syntax and emits a `promptfile/variables` warning listing unresolved inputs and the deferred declaration checks. Supply repeated `--var key=value` flags or a `--vars` JSON object to enable those checks. Schema compilation uses bundled declarations and does not fetch external references. + +Results use Gavel's standard linter-result array, including stable rule IDs, severities, file counts, and source positions where available. Warning-only results exit successfully; invalid content or execution failures exit nonzero. JSON output retains diagnostics on failure. The command performs validation only and does not modify promptfiles. diff --git a/examples/lint-review.prompt b/examples/lint-review.prompt new file mode 100644 index 00000000..74fab1c6 --- /dev/null +++ b/examples/lint-review.prompt @@ -0,0 +1,9 @@ +--- +description: A reusable review prompt with a templated output-token budget. +budget: + maxTokens: {{limit}} +--- +{{role "system"}} +Review the supplied text for concrete correctness issues. +{{role "user"}} +{{text}} diff --git a/go.mod b/go.mod index 95cd25ed..b14b862a 100644 --- a/go.mod +++ b/go.mod @@ -16,7 +16,7 @@ require ( github.com/fsnotify/fsnotify v1.10.1 github.com/google/cel-go v0.31.0 github.com/google/dotprompt/go v0.0.0-20260708220100-73beb993ac95 - github.com/google/uuid v1.6.0 + github.com/google/uuid v1.6.1-0.20241114170450-2d3c2a9cc518 github.com/invopop/jsonschema v0.14.0 github.com/onsi/ginkgo/v2 v2.32.1 github.com/onsi/gomega v1.42.1 @@ -32,24 +32,36 @@ require ( golang.org/x/oauth2 v0.36.0 golang.org/x/term v0.44.0 gopkg.in/yaml.v3 v3.0.1 - k8s.io/api v0.36.1 + k8s.io/api v0.36.2 k8s.io/apimachinery v0.36.2 - k8s.io/client-go v0.36.1 + k8s.io/client-go v0.36.2 mvdan.cc/sh/v3 v3.13.0 sigs.k8s.io/yaml v1.6.0 ) require ( - github.com/flanksource/commons-db v0.1.61-0.20261027210213-a7b138ebccde + github.com/flanksource/commons-db v0.1.61 + github.com/flanksource/gavel v0.0.57 github.com/gliderlabs/ssh v0.3.8 github.com/pb33f/ordered-map/v2 v2.3.1 github.com/pelletier/go-toml/v2 v2.4.3 ) require ( + cloud.google.com/go/bigquery v1.77.0 // indirect + cloud.google.com/go/logging v1.18.0 // indirect + github.com/Azure/azure-sdk-for-go/sdk/monitor/azquery v1.2.0 // indirect github.com/alpkeskin/gotoon v0.1.1 // indirect + github.com/apache/arrow/go/v15 v15.0.2 // indirect github.com/atombender/go-jsonschema v0.24.1 // indirect + github.com/aws/aws-sdk-go-v2/service/cloudwatchlogs v1.75.2 // indirect + github.com/creack/pty v1.1.24 // indirect github.com/ebitengine/purego v0.10.2 // indirect + github.com/elazarl/goproxy v1.7.2 // indirect + github.com/flanksource/commons-db/cmd/query v0.1.61 // indirect + github.com/flanksource/commons-db/recordstore v0.1.61 // indirect + github.com/flanksource/commons-db/tracing v0.1.61 // indirect + github.com/flanksource/repomap v0.4.1 // indirect github.com/flanksource/sqlglot-go v1.0.4-0.20261022123344-3264e440e925 // indirect github.com/glebarez/sqlite v1.11.0 // indirect github.com/go-openapi/swag/cmdutils v0.25.4 // indirect @@ -62,13 +74,20 @@ require ( github.com/go-openapi/swag/stringutils v0.25.4 // indirect github.com/go-openapi/swag/typeutils v0.25.4 // indirect github.com/go-openapi/swag/yamlutils v0.25.4 // indirect + github.com/goccy/go-json v0.10.6 // indirect + github.com/google/flatbuffers v25.12.19+incompatible // indirect + github.com/google/gops v0.3.29 // indirect github.com/hexops/gotextdiff v1.0.3 // indirect + github.com/maruel/panicparse/v2 v2.5.0 // indirect github.com/ncruces/go-strftime v1.0.0 // indirect + github.com/opensearch-project/opensearch-go/v2 v2.3.0 // indirect github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect github.com/sanity-io/litter v1.5.8 // indirect github.com/shirou/gopsutil/v4 v4.26.7 // indirect github.com/sosodev/duration v1.4.0 // indirect + github.com/zeebo/xxh3 v1.1.0 // indirect go.yaml.in/yaml/v4 v4.0.0-rc.4 // indirect + golang.org/x/telemetry v0.0.0-20260625142307-59b4966ccb57 // indirect google.golang.org/grpc/cmd/protoc-gen-go-grpc v1.6.2 // indirect gorm.io/driver/sqlserver v1.6.4 // indirect modernc.org/libc v1.74.1 // indirect @@ -88,7 +107,7 @@ require ( github.com/fergusstrange/embedded-postgres v1.34.0 // indirect github.com/go-openapi/inflect v0.21.5 // indirect github.com/gofrs/flock v0.13.0 // indirect - github.com/google/jsonschema-go v0.4.2 // indirect + github.com/google/jsonschema-go v0.4.3 // indirect github.com/hashicorp/hcl/v2 v2.24.0 // indirect github.com/mitchellh/go-wordwrap v1.0.1 // indirect github.com/nukilabs/ftoa v1.0.0 // indirect @@ -171,7 +190,7 @@ require ( github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834 // indirect github.com/charmbracelet/x/ansi v0.11.6 github.com/charmbracelet/x/cellbuf v0.0.15 // indirect - github.com/charmbracelet/x/exp/strings v0.0.0-20240722160745-212f7b056ed0 // indirect + github.com/charmbracelet/x/exp/strings v0.0.0-20260122224438-b01af16209d9 // indirect github.com/charmbracelet/x/term v0.2.2 // indirect github.com/clipperhouse/displaywidth v0.11.0 // indirect github.com/clipperhouse/uax29/v2 v2.7.0 // indirect @@ -222,7 +241,7 @@ require ( github.com/google/btree v1.1.3 // indirect github.com/google/gnostic-models v0.7.1 // indirect github.com/google/go-cmp v0.7.0 // indirect - github.com/google/pprof v0.0.0-20260402051712-545e8a4df936 // indirect + github.com/google/pprof v0.0.0-20260507013755-92041b743c96 // indirect github.com/google/s2a-go v0.1.9 // indirect github.com/googleapis/enterprise-certificate-proxy v0.3.17 // indirect github.com/googleapis/gax-go/v2 v2.22.0 // indirect @@ -283,7 +302,7 @@ require ( github.com/openai/openai-go v1.12.0 github.com/opencontainers/go-digest v1.0.0 // indirect github.com/orcaman/concurrent-map/v2 v2.0.1 // indirect - github.com/patrickmn/go-cache v2.1.0+incompatible // indirect + github.com/patrickmn/go-cache v2.1.1-0.20191004192108-46f407853014+incompatible // indirect github.com/paulmach/orb v0.12.0 // indirect github.com/peterbourgon/diskv v2.0.1+incompatible // indirect github.com/pierrec/lz4/v4 v4.1.26 // indirect @@ -291,7 +310,7 @@ require ( github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c // indirect github.com/pkg/errors v0.9.1 // indirect github.com/pkg/sftp v1.13.10 // indirect - github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10 // indirect + github.com/planetscale/vtprotobuf v0.6.1-0.20250313105119-ba97887b0a25 // indirect github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 // indirect github.com/prometheus/client_golang v1.23.2 // indirect @@ -369,7 +388,7 @@ require ( gopkg.in/warnings.v0 v0.1.2 // indirect gopkg.in/yaml.v2 v2.4.0 // indirect gorm.io/gorm v1.31.2 - k8s.io/apiextensions-apiserver v0.36.1 // indirect + k8s.io/apiextensions-apiserver v0.36.2 // indirect k8s.io/klog/v2 v2.140.0 // indirect k8s.io/kube-openapi v0.0.0-20260317180543-43fb72c5454a // indirect k8s.io/streaming v0.36.2 // indirect diff --git a/go.sum b/go.sum index 4cc617b6..230ad87b 100644 --- a/go.sum +++ b/go.sum @@ -9,10 +9,14 @@ cloud.google.com/go/auth v0.20.0 h1:kXTssoVb4azsVDoUiF8KvxAqrsQcQtB53DcSgta74CA= cloud.google.com/go/auth v0.20.0/go.mod h1:942/yi/itH1SsmpyrbnTMDgGfdy2BUqIKyd0cyYLc5Q= cloud.google.com/go/auth/oauth2adapt v0.2.8 h1:keo8NaayQZ6wimpNSmW5OPc283g65QNIiLpZnkHRbnc= cloud.google.com/go/auth/oauth2adapt v0.2.8/go.mod h1:XQ9y31RkqZCcwJWNSx2Xvric3RrU88hAYYbjDWYDL+c= +cloud.google.com/go/bigquery v1.77.0 h1:L5AW3jhzEKpFVg4i0mVHxKpxogrqT7dczWBSr4m9MKU= +cloud.google.com/go/bigquery v1.77.0/go.mod h1:J4wuqka/1hEpdJxH2oBrUR0vjTD+r7drGkpcA3yqERM= cloud.google.com/go/cloudsqlconn v1.22.1 h1:c4HkWMSV4pDL8kJid+nIuF+6iE07pR5Mn/sRVY17wf4= cloud.google.com/go/cloudsqlconn v1.22.1/go.mod h1:p7l+u0ThOzSvC5a4fkywi1hEyD8S709X1zEqux9tsq0= cloud.google.com/go/compute/metadata v0.9.0 h1:pDUj4QMoPejqq20dK0Pg2N4yG9zIkYGdBtwLoEkH9Zs= cloud.google.com/go/compute/metadata v0.9.0/go.mod h1:E0bWwX5wTnLPedCKqk3pJmVgCBSM6qQI1yTBdEb3C10= +cloud.google.com/go/datacatalog v1.27.0 h1:AnghhtHKCqYIe62gTPHcn9nJr5jtxjZHV4D/Fob23gg= +cloud.google.com/go/datacatalog v1.27.0/go.mod h1:YTI11pFlC5HCj4CphEf+qWCy/z9udd7o0HVN6c2Povg= cloud.google.com/go/iam v1.7.0 h1:JD3zh0C6LHl16aCn5Akff0+GELdp1+4hmh6ndoFLl8U= cloud.google.com/go/iam v1.7.0/go.mod h1:tetWZW1PD/m6vcuY2Zj/aU0eCHNPuxedbnbRTyKXvdY= cloud.google.com/go/kms v1.26.0 h1:cK9mN2cf+9V63D3H1f6koxTatWy39aTI/hCjz1I+adU= @@ -43,10 +47,14 @@ github.com/Azure/azure-sdk-for-go/sdk/keyvault/azkeys v0.10.0 h1:m/sWOGCREuSBqg2 github.com/Azure/azure-sdk-for-go/sdk/keyvault/azkeys v0.10.0/go.mod h1:Pu5Zksi2KrU7LPbZbNINx6fuVrUp/ffvpxdDj+i8LeE= github.com/Azure/azure-sdk-for-go/sdk/keyvault/internal v0.7.1 h1:FbH3BbSb4bvGluTesZZ+ttN/MDsnMmQP36OSnDuSXqw= github.com/Azure/azure-sdk-for-go/sdk/keyvault/internal v0.7.1/go.mod h1:9V2j0jn9jDEkCkv8w/bKTNppX/d0FVA1ud77xCIP4KA= +github.com/Azure/azure-sdk-for-go/sdk/monitor/azquery v1.2.0 h1:s0SaQtHigowP0n3Kx4ieV94pNZAHlHhS+xjZyLCSVCQ= +github.com/Azure/azure-sdk-for-go/sdk/monitor/azquery v1.2.0/go.mod h1:oI5SPI1vpNJYfP9MPWXthq7jDfh9xTAuQVBKPOu7DPo= github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azkeys v1.4.0 h1:E4MgwLBGeVB5f2MdcIVD3ELVAWpr+WD6MUe1i+tM/PA= github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azkeys v1.4.0/go.mod h1:Y2b/1clN4zsAoUd/pgNAQHjLDnTis/6ROkUfyob6psM= github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/internal v1.2.0 h1:nCYfgcSyHZXJI8J0IWE5MsCGlb2xp9fJiXyxWgmOFg4= github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/internal v1.2.0/go.mod h1:ucUjca2JtSZboY8IoUqyQyuuXvwbMBVwFOm0vdQPNhA= +github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c h1:udKWzYgxTojEKWjV8V+WSxDXJ4NFATAsZjh8iIbsQIg= +github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c/go.mod h1:xomTg63KZ2rFqZQzSB4Vz2SUXa1BpHTVz9L5PTmPC4E= github.com/AzureAD/microsoft-authentication-extensions-for-go/cache v0.1.1 h1:WJTmL004Abzc5wDB5VtZG2PJk5ndYDgVacGqfirKxjM= github.com/AzureAD/microsoft-authentication-extensions-for-go/cache v0.1.1/go.mod h1:tCcJZ0uHAmvjsVYzEFivsRTN00oz5BEsRgQHu5JZ9WE= github.com/AzureAD/microsoft-authentication-library-for-go v1.7.2 h1:RHK7bS+HQMslb1sZpAokUt+zTVmue0hKSs2C791hhzU= @@ -83,12 +91,16 @@ github.com/TomOnTime/utfutil v1.0.0 h1:/0Ivgo2OjXJxo8i7zgvs7ewSFZMLwCRGm3P5Umowb github.com/TomOnTime/utfutil v1.0.0/go.mod h1:l9lZmOniizVSuIliSkEf87qivMRlSNzbdBFKjuLRg1c= github.com/agext/levenshtein v1.2.3 h1:YB2fHEn0UJagG8T1rrWknE3ZQzWM06O8AMAatNn7lmo= github.com/agext/levenshtein v1.2.3/go.mod h1:JEDfjyjHDjOF/1e4FlBE/PkbqA9OfWu2ki2W0IB5558= +github.com/agnivade/levenshtein v1.2.1 h1:EHBY3UOn1gwdy/VbFwgo4cxecRznFk7fKWN1KOX7eoM= +github.com/agnivade/levenshtein v1.2.1/go.mod h1:QVVI16kDrtSuwcpd0p1+xMC6Z/VfhtCyDIjcwga4/DU= github.com/alecthomas/assert/v2 v2.11.0 h1:2Q9r3ki8+JYXvGsDyBXwH3LcJ+WK5D0gc5E8vS6K3D0= github.com/alecthomas/assert/v2 v2.11.0/go.mod h1:Bze95FyfUr7x34QZrjL+XP+0qgp/zg8yS+TtBj1WA3k= github.com/alecthomas/chroma/v2 v2.23.1 h1:nv2AVZdTyClGbVQkIzlDm/rnhk1E9bU9nXwmZ/Vk/iY= github.com/alecthomas/chroma/v2 v2.23.1/go.mod h1:NqVhfBR0lte5Ouh3DcthuUCTUpDC9cxBOfyMbMQPs3o= github.com/alecthomas/repr v0.5.2 h1:SU73FTI9D1P5UNtvseffFSGmdNci/O6RsqzeXJtP0Qs= github.com/alecthomas/repr v0.5.2/go.mod h1:Fr0507jx4eOXV7AlPV6AVZLYrLIuIeSOWtW57eE/O/4= +github.com/alicebob/miniredis/v2 v2.38.0 h1:nZAzCR+Lj+Vxk4ZXzm2NuKq2O33RXj1XxJ2e2uP9jiw= +github.com/alicebob/miniredis/v2 v2.38.0/go.mod h1:TcL7YfarKPGDAthEtl5NBeHZfeUQj6OXMm/+iu5cLMM= github.com/alpkeskin/gotoon v0.1.1 h1:GQOVwMfWKINnfEA6slrXHJaJYDwnUFmrPlXOtnuja1w= github.com/alpkeskin/gotoon v0.1.1/go.mod h1:XRTz8RM4tz8M2nB37MNRN8rHF4YgeYd8nIXmoU0B0+M= github.com/andybalholm/brotli v1.2.0 h1:ukwgCxwYrmACq68yiUqwIWnGY0cTPox/M94sVwToPjQ= @@ -103,6 +115,8 @@ github.com/anthropics/anthropic-sdk-go v1.26.0 h1:oUTzFaUpAevfuELAP1sjL6CQJ9HHAf github.com/anthropics/anthropic-sdk-go v1.26.0/go.mod h1:qUKmaW+uuPB64iy1l+4kOSvaLqPXnHTTBKH6RVZ7q5Q= github.com/antlr4-go/antlr/v4 v4.13.1 h1:SqQKkuVZ+zWkMMNkjy5FZe5mr5WURWnlpmOuzYWrPrQ= github.com/antlr4-go/antlr/v4 v4.13.1/go.mod h1:GKmUxMtwp6ZgGwZSva4eWPC5mS6vUAmOABFgjdkM7Nw= +github.com/apache/arrow/go/v15 v15.0.2 h1:60IliRbiyTWCWjERBCkO1W4Qun9svcYoZrSLcyOsMLE= +github.com/apache/arrow/go/v15 v15.0.2/go.mod h1:DGXsR3ajT524njufqf95822i+KTh+yea1jass9YXgjA= github.com/apparentlymart/go-textseg/v15 v15.0.0 h1:uYvfpb3DyLSCGWnctWKGj857c6ew1u1fNQOlOtuGxQY= github.com/apparentlymart/go-textseg/v15 v15.0.0/go.mod h1:K8XmNZdhEBkdlyDdvbmmsvpAG721bKi0joRfFdHIWJ4= github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5 h1:0CwZNZbxp69SHPdPJAN/hZIm0C4OItdklCFmMRWYpio= @@ -111,28 +125,39 @@ github.com/atombender/go-jsonschema v0.24.1 h1:Vb2JHFA0AxtMl8F1ecrpMQ3uQ2Cxm0Hgp github.com/atombender/go-jsonschema v0.24.1/go.mod h1:yYMQVvK3WlxXJIpciA84rKg/xf2VCxIsxNt9I7Ugvmw= github.com/atotto/clipboard v0.1.4 h1:EH0zSVneZPSuFR11BlR9YppQTVDbh5+16AmcJi4g1z4= github.com/atotto/clipboard v0.1.4/go.mod h1:ZY9tmq7sm5xIbd9bOK4onWV4S6X0u6GY7Vn0Yu86PYI= +github.com/aws/aws-sdk-go v1.44.263/go.mod h1:aVsgQcEevwlmQ7qHE9I3h+dtQgpqhFB+i8Phjh7fkwI= +github.com/aws/aws-sdk-go-v2 v1.18.0/go.mod h1:uzbQtefpm44goOPmdKyAlXSNcwlRgF3ePWVW6EtJvvw= github.com/aws/aws-sdk-go-v2 v1.42.0 h1:XvXMJTkFQtpBKIWZnmr9ZEOc2InWM2yldjXEJ/bymhA= github.com/aws/aws-sdk-go-v2 v1.42.0/go.mod h1:27+ACypSLljLAEKsCYOmrjKh83vuTRkuAe9Uv/3A4bg= github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.13 h1:p1BBrg/Hhp6uK7zpejeI8QFXHJeC/mynzi04Sl03k9g= github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.13/go.mod h1:8cIfkE9MDhkRZGpQ22aV6/lkYeYSozpz16Smrs5x4Ls= +github.com/aws/aws-sdk-go-v2/config v1.18.25/go.mod h1:dZnYpD5wTW/dQF0rRNLVypB396zWCcPiBIvdvSWHEg4= github.com/aws/aws-sdk-go-v2/config v1.32.25 h1:ACCejvStYoilgwrfegSt5ZntCbPrk52qfwyNcnl3omM= github.com/aws/aws-sdk-go-v2/config v1.32.25/go.mod h1:LJyU8sDRbXUxFn8xMJIGP+v9QYYwveNLI8a/giAOiAs= +github.com/aws/aws-sdk-go-v2/credentials v1.13.24/go.mod h1:jYPYi99wUOPIFi0rhiOvXeSEReVOzBqFNOX5bXYoG2o= github.com/aws/aws-sdk-go-v2/credentials v1.19.24 h1:2hQqYCV9yqyePQ9o6dCrZc/zO8U3TwPr9mIKlZnPu/I= github.com/aws/aws-sdk-go-v2/credentials v1.19.24/go.mod h1:IDwpACtwqHLISdzfwUUNq4P9DsB/h5BLg4FwJPNfqFY= +github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.13.3/go.mod h1:4Q0UFP0YJf0NrsEuEYHpM9fTSEVnD16Z3uyEF7J9JGM= github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.29 h1:r6qZHbT+wxgWO/e9vYNUEtg7lv5+UN3pRqKhLXvnArg= github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.29/go.mod h1:QRnaRcTVGKPGRy8w78HMQtKUGRYcnMZAANATkeVA6Mo= +github.com/aws/aws-sdk-go-v2/internal/configsources v1.1.33/go.mod h1:7i0PF1ME/2eUPFcjkVIwq+DOygHEoK92t5cDqNgYbIw= github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.29 h1:f3vKqSo13fhTYb+JEcXwXefZQE26I1FB5eTSniU67ko= github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.29/go.mod h1:MzoLFUArKGpGD+ukmPiTPG1X5x4o6M2kq4v2dr1FiEc= +github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.4.27/go.mod h1:UrHnn3QV/d0pBZ6QBAEQcqFLf8FAzLmoUfPVIueOvoM= github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.29 h1:RdwIf/CuUsvJX3RgJagbOyotl/cxoLY4xviKuE7p2GY= github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.29/go.mod h1:71wt8W2EgswdZy9Mf9KNnzxZ3TiZlv4caKghPktDOkA= +github.com/aws/aws-sdk-go-v2/internal/ini v1.3.34/go.mod h1:Etz2dj6UHYuw+Xw830KfzCfWGMzqvUTCjUj5b76GVDc= github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.30 h1:VTGy885W5DKBxWRUJbym9hytNaYzsyaPkCHGRRMAOhU= github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.30/go.mod h1:AS0HycUvJRFvTt613AYDOgO2jzw+00cVSMny8XB3yMY= +github.com/aws/aws-sdk-go-v2/service/cloudwatchlogs v1.75.2 h1:qXso3xK+5GmfBq8n/ymjJB12kHkO3Yhy9+8cIHlw6J4= +github.com/aws/aws-sdk-go-v2/service/cloudwatchlogs v1.75.2/go.mod h1:N336OxQ6TvRbb6V1esVE8PtQFU86YvYaS+lVjsJTmP0= github.com/aws/aws-sdk-go-v2/service/eks v1.84.6 h1:RSCziGPe92ZoBreWKOJsLhK45Nx7+2b2y8hNbOUvHLQ= github.com/aws/aws-sdk-go-v2/service/eks v1.84.6/go.mod h1:rbIASs+SfCDUXx2EdfMkNpDGptlW8hvMZ9AawRiUBqE= github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.12 h1:ZD2+BSw9vFsNlKYIasSNt3uDbjqqXIBcM13UJv/Lx2k= github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.12/go.mod h1:Ms4zlcVBbXbiP7EVLhl+lgjvA/a7YphqQ3Ih3174EmI= github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.9.18 h1:W/EyPFl9A5rXrtoilfwHYEvzHER+K4SpBPtMXi24Mos= github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.9.18/go.mod h1:UG50K+pvd/uy6xExbobg0rjqFBFZe6I3l75EPDZw4tg= +github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.9.27/go.mod h1:EOwBD4J4S5qYszS5/3DpkejfuK+Z5/1uzICfPaZLtqw= github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.29 h1:DRebniUGZ2MqiiIVmQJ04vIXr918hubdHMnarSLEWyU= github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.29/go.mod h1:LfRkPCD8YHDM2E5eTkos2UpwYeZnBcVarTa8L59bJHA= github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.19.25 h1:2pQEbwf+/6EDbiit/GcBE2K4IUpMZymaA0kOz3xK978= @@ -143,12 +168,16 @@ github.com/aws/aws-sdk-go-v2/service/s3 v1.102.2 h1:ie4ElCmUKS26pzrZcIk/lmt4yWjA github.com/aws/aws-sdk-go-v2/service/s3 v1.102.2/go.mod h1:zjsomFeX5duj+4PlMB+o4JoWTIx+G0XMyzjYrUbQkN0= github.com/aws/aws-sdk-go-v2/service/signin v1.2.0 h1:3nXpRcFwRCW8n7HgO2QGy0Dc20eQNfBuUemGQhpF8m8= github.com/aws/aws-sdk-go-v2/service/signin v1.2.0/go.mod h1:LxYujSTLPRlp2vTtcUO/+1ilrew8ytt6SvQyOgejzFQ= +github.com/aws/aws-sdk-go-v2/service/sso v1.12.10/go.mod h1:ouy2P4z6sJN70fR3ka3wD3Ro3KezSxU6eKGQI2+2fjI= github.com/aws/aws-sdk-go-v2/service/sso v1.31.3 h1:ey1XLTYXb9PcLt4535632o5kCGXNXEhNb620Dqwuylo= github.com/aws/aws-sdk-go-v2/service/sso v1.31.3/go.mod h1:Lk7PlmoTYryQmyBG0EXqj5BcUbj3whXdU2s3yGI3EAc= +github.com/aws/aws-sdk-go-v2/service/ssooidc v1.14.10/go.mod h1:AFvkxc8xfBe8XA+5St5XIHHrQQtkxqrRincx4hmMHOk= github.com/aws/aws-sdk-go-v2/service/ssooidc v1.36.6 h1:yLr03zQE/5Eu5l3QU0Si+xMbLMbSDF2YXsigqXngs6g= github.com/aws/aws-sdk-go-v2/service/ssooidc v1.36.6/go.mod h1:Q5N6icH+KJZDLh+ESNwzdv6cZ6vLFF/egy3IOxWhmz4= +github.com/aws/aws-sdk-go-v2/service/sts v1.19.0/go.mod h1:BgQOMsg8av8jset59jelyPW7NoZcZXLVpDsXunGDrk8= github.com/aws/aws-sdk-go-v2/service/sts v1.43.3 h1:VrIhKRCSK1umelSgB9RghvA9RTUYeQffyAS5ApXehNI= github.com/aws/aws-sdk-go-v2/service/sts v1.43.3/go.mod h1:r8wkDOuLaaMFqFiYAb8dGY2A3gJCOujMc6CFOVC4Zhc= +github.com/aws/smithy-go v1.13.5/go.mod h1:Tg+OJXh4MB2R/uN61Ko2f6hTZwB/ZYGOtib8J3gBHzA= github.com/aws/smithy-go v1.27.1 h1:4T340VFndXtADGF52gYa1POyL7s9E4Z1OeZ1hCscIw8= github.com/aws/smithy-go v1.27.1/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc= github.com/aymanbagabas/go-osc52/v2 v2.0.1 h1:HwpRHbFMcZLEVr42D4p7XBqjyuxQH5SMiErDT4WkJ2k= @@ -167,8 +196,12 @@ github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA= github.com/bsm/gomega v1.27.10/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0= github.com/buger/jsonparser v1.1.2 h1:frqHqw7otoVbk5M8LlE/L7HTnIq2v9RX6EJ48i9AxJk= github.com/buger/jsonparser v1.1.2/go.mod h1:6RYKKt7H4d4+iWqouImQ9R2FZql3VbhNgx27UK13J/0= +github.com/caarlos0/env/v11 v11.3.1 h1:cArPWC15hWmEt+gWk7YBi7lEXTXCvpaSdCiZE2X5mCA= +github.com/caarlos0/env/v11 v11.3.1/go.mod h1:qupehSf/Y0TUTsxKywqRt/vJjN5nz6vauiYEUUr8P4U= github.com/catppuccin/go v0.3.0 h1:d+0/YicIq+hSTo5oPuRi5kOpqkVA5tAsU6dNhvRu+aY= github.com/catppuccin/go v0.3.0/go.mod h1:8IHJuMGaUUjQM82qBrGNBv7LFq6JI3NnQCF6MOlZjpc= +github.com/cenkalti/backoff/v4 v4.3.0 h1:MyRJ/UdXutAwSAT+s3wNd7MfTIcy71VQueUuFK343L8= +github.com/cenkalti/backoff/v4 v4.3.0/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyYozVcomhLiZE= github.com/cenkalti/backoff/v5 v5.0.3 h1:ZN+IMa753KfX5hd8vVaMixjnqRZ3y8CuJKRKj1xcsSM= github.com/cenkalti/backoff/v5 v5.0.3/go.mod h1:rkhZdG3JZukswDf7f0cwqPNk4K0sa+F97BxZthm/crw= github.com/census-instrumentation/opencensus-proto v0.2.1/go.mod h1:f6KPmirojxKA12rnyqOA5BBL4O983OfeGPqjHWSTneU= @@ -196,8 +229,8 @@ github.com/charmbracelet/x/errors v0.0.0-20240508181413-e8d8b6e2de86 h1:JSt3B+U9 github.com/charmbracelet/x/errors v0.0.0-20240508181413-e8d8b6e2de86/go.mod h1:2P0UgXMEa6TsToMSuFqKFQR+fZTO9CNGUNokkPatT/0= github.com/charmbracelet/x/exp/golden v0.0.0-20250806222409-83e3a29d542f h1:pk6gmGpCE7F3FcjaOEKYriCvpmIN4+6OS/RD0vm4uIA= github.com/charmbracelet/x/exp/golden v0.0.0-20250806222409-83e3a29d542f/go.mod h1:IfZAMTHB6XkZSeXUqriemErjAWCCzT0LwjKFYCZyw0I= -github.com/charmbracelet/x/exp/strings v0.0.0-20240722160745-212f7b056ed0 h1:qko3AQ4gK1MTS/de7F5hPGx6/k1u0w4TeYmBFwzYVP4= -github.com/charmbracelet/x/exp/strings v0.0.0-20240722160745-212f7b056ed0/go.mod h1:pBhA0ybfXv6hDjQUZ7hk1lVxBiUbupdw5R31yPUViVQ= +github.com/charmbracelet/x/exp/strings v0.0.0-20260122224438-b01af16209d9 h1:JevRYfkTT0sN9OIXAOncYNC0cTP1Gml/0mCSnsmRkRk= +github.com/charmbracelet/x/exp/strings v0.0.0-20260122224438-b01af16209d9/go.mod h1:/ehtMPNh9K4odGFkqYJKpIYyePhdp1hLBRvyY4bWkH8= github.com/charmbracelet/x/term v0.2.2 h1:xVRT/S2ZcKdhhOuSP4t5cLi5o+JxklsoEObBSgfgZRk= github.com/charmbracelet/x/term v0.2.2/go.mod h1:kF8CY5RddLWrsgVwpw4kAa6TESp6EB5y3uxGLeCqzAI= github.com/charmbracelet/x/termios v0.1.1 h1:o3Q2bT8eqzGnGPOYheoYS8eEleT5ZVNYNy8JawjaNZY= @@ -218,6 +251,14 @@ github.com/cncf/xds/go v0.0.0-20260202195803-dba9d589def2 h1:aBangftG7EVZoUb69Os github.com/cncf/xds/go v0.0.0-20260202195803-dba9d589def2/go.mod h1:qwXFYgsP6T7XnJtbKlf1HP8AjxZZyzxMmc+Lq5GjlU4= github.com/coder/websocket v1.8.14 h1:9L0p0iKiNOibykf283eHkKUHHrpG7f65OE3BhhO7v9g= github.com/coder/websocket v1.8.14/go.mod h1:NX3SzP+inril6yawo5CQXx8+fk145lPDC6pumgx0mVg= +github.com/containerd/errdefs v1.0.0 h1:tg5yIfIlQIrxYtu9ajqY42W3lpS19XqdxRQeEwYG8PI= +github.com/containerd/errdefs v1.0.0/go.mod h1:+YBYIdtsnF4Iw6nWZhJcqGSg/dwvV7tyJ/kCkyJ2k+M= +github.com/containerd/errdefs/pkg v0.3.0 h1:9IKJ06FvyNlexW690DXuQNx2KA2cUJXx151Xdx3ZPPE= +github.com/containerd/errdefs/pkg v0.3.0/go.mod h1:NJw6s9HwNuRhnjJhM7pylWwMyAkmCQvQ4GpJHEqRLVk= +github.com/containerd/log v0.1.0 h1:TCJt7ioM2cr/tfR8GPbGf9/VRAX8D2B4PjzCpfX540I= +github.com/containerd/log v0.1.0/go.mod h1:VRRf09a7mHDIRezVKTRCrOq78v577GXq3bSa3EhrzVo= +github.com/containerd/platforms v0.2.1 h1:zvwtM3rz2YHPQsF2CHYM8+KtB5dvhISiXh5ZpSBQv6A= +github.com/containerd/platforms v0.2.1/go.mod h1:XHCb+2/hzowdiut9rkudds9bE5yJ7npe7dG/wG+uFPw= github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g= github.com/creack/pty v1.1.24 h1:bJrF4RRfyJnbTJqzRLHzcGaZK1NeM5kTC9jGgovnR1s= github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE= @@ -234,6 +275,22 @@ github.com/dlclark/regexp2 v1.11.5 h1:Q/sSnsKerHeCkc/jSTNq1oCm7KiVgUMZRDUoRu0JQZ github.com/dlclark/regexp2 v1.11.5/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8= github.com/dnaeon/go-vcr v1.2.0 h1:zHCHvJYTMh1N7xnV7zf1m1GPBF9Ad0Jk/whtQ1663qI= github.com/dnaeon/go-vcr v1.2.0/go.mod h1:R4UdLID7HZT3taECzJs4YgbbH6PIGXB6W/sc5OLb6RQ= +github.com/docker/go-connections v0.7.0 h1:6SsRfJddP22WMrCkj19x9WKjEDTB+ahsdiGYf0mN39c= +github.com/docker/go-connections v0.7.0/go.mod h1:no1qkHdjq7kLMGUXYAduOhYPSJxxvgWBh7ogVvptn3Q= +github.com/docker/go-sdk/client v0.1.0-alpha013 h1:FtIFLXjwSkQuOA4k6eE4Erz1nfW0d5Aq/lxID/d4Lpw= +github.com/docker/go-sdk/client v0.1.0-alpha013/go.mod h1:6AWYuKRnvTXp+rWYHDrWUui0Aykgl8JdjttukngnKE0= +github.com/docker/go-sdk/config v0.1.0-alpha013 h1:AbVVhOjtuyzlireZ8kJrzd3Xlrqz6CafsBQjLGKOipA= +github.com/docker/go-sdk/config v0.1.0-alpha013/go.mod h1:Eq39AVh06RUJ50fLvJHFKM80P9kZWTiog1x7NzrndBg= +github.com/docker/go-sdk/container v0.1.0-alpha016 h1:qvE173H6pDykJl5zXufDhp0nK4HSPjkfd5gjA+fPjvM= +github.com/docker/go-sdk/container v0.1.0-alpha016/go.mod h1:O0mTuDUPrl6x8BwwL53k1Q0C6wDoUp4xAmE1uLzjszw= +github.com/docker/go-sdk/context v0.1.0-alpha013 h1:he+yf7bEAOvDdeRkkd+vNFHiGhmZV2oSx0j7s9lI7e8= +github.com/docker/go-sdk/context v0.1.0-alpha013/go.mod h1:a+3Mdx3Tss56tN5bajB3YfW29ZHdm6nenlB6yxIaeF4= +github.com/docker/go-sdk/image v0.1.0-alpha015 h1:y0KqSQadpLMURL0jgA8HO79M0nHwQXEjmalPxxAqNwo= +github.com/docker/go-sdk/image v0.1.0-alpha015/go.mod h1:ujOXFWntnGkARHfXiIK/nonx6+8eQLqjWMb9wL35s0I= +github.com/docker/go-sdk/network v0.1.0-alpha013 h1:vl0F5LZLmuF9yBwJ9/6kPJqHOgevSFHNK82t9a2tejQ= +github.com/docker/go-sdk/network v0.1.0-alpha013/go.mod h1:kgEPlBmaYjQwO+a+6IfQmLvo6BC9x8106TbJBBEXF6w= +github.com/docker/go-units v0.5.0 h1:69rxXcBk27SvSaaxTtLh/8llcHD8vYHT7WSdRZ/jvr4= +github.com/docker/go-units v0.5.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDDbaIK4Dk= github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY= github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto= github.com/ebitengine/purego v0.10.2 h1:W809HbnvzAxgdm+aOvlSekrM16wGCdT/e76+9tS7gzE= @@ -274,16 +331,32 @@ github.com/flanksource/clicky v1.21.88-0.20261027204456-34e65b99d69d h1:S8zFjrGZ github.com/flanksource/clicky v1.21.88-0.20261027204456-34e65b99d69d/go.mod h1:2hh1pw/svkWomN+Ah946CD7zcwuGxvRSnR0PTSqMe/Y= github.com/flanksource/clicky/aichat v1.21.82 h1:ccvtLRaQCQlAN+FVF3jp6I71CdycQwKrpicYB0ZeaX0= github.com/flanksource/clicky/aichat v1.21.82/go.mod h1:Wa5PhmTSCimtWVu5KIy+PG7+x9+EICQPNlH6O83+dM0= +github.com/flanksource/clicky/valkey v1.21.82 h1:6R0Uysg4pJfVu1RmUqdXQqHLhtutHqy24tsAESwa5Ns= +github.com/flanksource/clicky/valkey v1.21.82/go.mod h1:ulGU+1dpyJZ106CS3fMinoVZ8lec2zaJDhWxqCLFa+o= github.com/flanksource/commons v1.61.1-0.20261027203923-c5cfedcdae97 h1:vwBa3L3UPL7+zcJ+gG6NH1cZ8AAH4XxShkd+AQ4uY4Y= github.com/flanksource/commons v1.61.1-0.20261027203923-c5cfedcdae97/go.mod h1:RlVSQ+Jq96jKaJWf3WnwVO4DmDTdzkm3sremzJuYuVw= -github.com/flanksource/commons-db v0.1.61-0.20261027210213-a7b138ebccde h1:QfMh6xZcg9/ksRl5k1Zpd1Enov932Z/xltj8hbRbLkY= -github.com/flanksource/commons-db v0.1.61-0.20261027210213-a7b138ebccde/go.mod h1:81yea1KIjO52xC2uoehwTd8BfnxSN+S6aoGYVDLuLp4= +github.com/flanksource/commons-db v0.1.61 h1:1SPMLToLUMVCPgNVsyqpQEx+o+iJFe/PtYT2Ng7uIjA= +github.com/flanksource/commons-db v0.1.61/go.mod h1:GO+KjECHjb4tUWoVnI1saqCMW517XtfsRaLkGKHpCNA= +github.com/flanksource/commons-db/cmd/query v0.1.61 h1:FrO/tpQiKiq55Ef0c81t/Apn0+891oIkFoSNiwuHOUY= +github.com/flanksource/commons-db/cmd/query v0.1.61/go.mod h1:yv0MFHjlQ10egPx5ZDGNSvCEmyAQ4P1bfwzenauWKZw= +github.com/flanksource/commons-db/recordstore v0.1.61 h1:GVTCBQUraHPrzqSw7bihBl68y8LexKZ5+GSh4vDKKkg= +github.com/flanksource/commons-db/recordstore v0.1.61/go.mod h1:Fw8oB8GoDfMng3Vsu2577tDKq7iljO5gCxFTrofapRM= +github.com/flanksource/commons-db/tracing v0.1.61 h1:xKHQNIvIpO94/82SqfvMsnjV0Fvmexa0REZ93M6nTK8= +github.com/flanksource/commons-db/tracing v0.1.61/go.mod h1:5sytYbY9LwrIldkQtI2ApSP7trxGDNjutRV6H9DrSho= +github.com/flanksource/deps v1.0.46 h1:+JCAghe8ELLm+xnMAk4AuTkavcAxd4IyvYukyk/5ypc= +github.com/flanksource/deps v1.0.46/go.mod h1:z7SozLaUD4TLemXxJytW67wGjCeQVLm2V10tdSg3pA4= +github.com/flanksource/deps/start v0.0.0-20261020081806-49e7d4bacc50 h1:lPRAjXprj1PMlnt3v4cZ7y37s1E0kThiTY7G+1PGwpM= +github.com/flanksource/deps/start v0.0.0-20261020081806-49e7d4bacc50/go.mod h1:eqA2vmlhjAqkIRMlWepLtZnuGQs7Lb8BLQ0ztAJF2Qg= +github.com/flanksource/gavel v0.0.57 h1:kKPSiougrTOmfDtQU9LofEsHBOlnjBaY4kgAezeFnHw= +github.com/flanksource/gavel v0.0.57/go.mod h1:4PDlOEqzieMscoKRdO9RJWCcZZSBTh90X2AD80d3qqM= github.com/flanksource/gomplate/v3 v3.24.90 h1:MAUlwU7REhSL62i4n74yvo+T4LA7HuRpJ9tKH9dbMzk= github.com/flanksource/gomplate/v3 v3.24.90/go.mod h1:tcjpBIaHboWVPUYt973dGLCWgTD1sOHdiFgA/AaPBPQ= github.com/flanksource/is-healthy v1.0.92 h1:15lC+p1RmyO1kOdZdpHdheqysgIK+hQD2ftSQ64gDg0= github.com/flanksource/is-healthy v1.0.92/go.mod h1:Gm46NfdDQsK9yDZNUNvkCm7jNnbl8R5vfcUYG3BgPXg= github.com/flanksource/kubectl-neat v1.0.4 h1:t5/9CqgE84oEtB0KitgJ2+WIeLfD+RhXSxYrqb4X8yI= github.com/flanksource/kubectl-neat v1.0.4/go.mod h1:Un/Voyh3cmiZNKQrW/TkAl28nAA7vwnwDGVjRErKjOw= +github.com/flanksource/repomap v0.4.1 h1:Cl5CiwYJX/NKes9qy0U3fKshO4jR0+wzND8+VfBIXII= +github.com/flanksource/repomap v0.4.1/go.mod h1:cEV1sJNWhOruzSU65LtH/k6kkjZSZW4rOUwl86DrO7w= github.com/flanksource/sandbox-runtime v1.0.2 h1:dEaVyUpeaCAn3GOiWcNDrPguaey1Gx9eTsPAc27W3Eg= github.com/flanksource/sandbox-runtime v1.0.2/go.mod h1:x5Ywc1MrP3lTgmj0VUCeFJzrDZ3mBhBV4Gdc/ioV76M= github.com/flanksource/sqlglot-go v1.0.4-0.20261022123344-3264e440e925 h1:sQGUeHC+LP/rhh9lNBbQ9our+JYY1cgHQYPSTZKiMSw= @@ -371,12 +444,14 @@ github.com/go-sql-driver/mysql v1.10.0 h1:Q+1LV8DkHJvSYAdR83XzuhDaTykuDx0l6fkXxo github.com/go-sql-driver/mysql v1.10.0/go.mod h1:M+cqaI7+xxXGG9swrdeUIoPG3Y3KCkF0pZej+SK+nWk= github.com/go-task/slim-sprig/v3 v3.0.0 h1:sUs3vkvUymDpBKi3qH1YSqBQk9+9D/8M2mN1vB6EwHI= github.com/go-task/slim-sprig/v3 v3.0.0/go.mod h1:W848ghGpv3Qj3dhTPRyJypKRiqCdHZiAzKg9hl15HA8= -github.com/go-test/deep v1.0.3 h1:ZrJSEWsXzPOxaZnFteGEfooLba+ju3FYIbOrS+rQd68= -github.com/go-test/deep v1.0.3/go.mod h1:wGDj63lr65AM2AQyKZd/NYHGb0R+1RLqB8NKt3aSFNA= +github.com/go-test/deep v1.1.1 h1:0r/53hagsehfO4bzD2Pgr/+RgHqhmf+k1Bpse2cTu1U= +github.com/go-test/deep v1.1.1/go.mod h1:5C2ZWiW0ErCdrYzpqxLbTX7MG14M9iiw8DgHncVwcsE= github.com/go-xmlfmt/xmlfmt v1.1.3 h1:t8Ey3Uy7jDSEisW2K3somuMKIpzktkWptA0iFCnRUWY= github.com/go-xmlfmt/xmlfmt v1.1.3/go.mod h1:aUCEOzzezBEjDBbFBoSiya/gduyIiWYRP6CnSFIV8AM= github.com/gobwas/glob v0.2.3 h1:A4xDbljILXROh+kObIiy5kIaPYD8e96x1tgBhUI5J+Y= github.com/gobwas/glob v0.2.3/go.mod h1:d3Ez4x06l9bZtSvzIay5+Yzi0fmZzPgnTbPcKjJAkT8= +github.com/goccy/go-json v0.10.6 h1:p8HrPJzOakx/mn/bQtjgNjdTcN+/S6FcG2CTtQOrHVU= +github.com/goccy/go-json v0.10.6/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M= github.com/goccy/go-yaml v1.19.2 h1:PmFC1S6h8ljIz6gMRBopkjP1TVT7xuwrButHID66PoM= github.com/goccy/go-yaml v1.19.2/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA= github.com/gofrs/flock v0.13.0 h1:95JolYOvGMqeH31+FC7D2+uULf6mG61mEZ/A8dRYMzw= @@ -413,6 +488,8 @@ github.com/google/cel-go v0.31.0 h1:H0bhpFTqOvmHrBGrWKp7ZlhBm5Hh8PYUEXnwxT1LL7A= github.com/google/cel-go v0.31.0/go.mod h1:X0bD6iVNR8pkROSOoHVdgTkzmRcosof7WQqCD6wcMc8= github.com/google/dotprompt/go v0.0.0-20260708220100-73beb993ac95 h1:SJdnmyOaT+kZNcUR+a1y2+Oa51j2ctCjYbtexaiXN68= github.com/google/dotprompt/go v0.0.0-20260708220100-73beb993ac95/go.mod h1:dnlL7KrFwJ7s8EJdsAp1WdLqOalJq1Sx2jWZnQkhFXs= +github.com/google/flatbuffers v25.12.19+incompatible h1:haMV2JRRJCe1998HeW/p0X9UaMTK6SDo0ffLn2+DbLs= +github.com/google/flatbuffers v25.12.19+incompatible/go.mod h1:1AeVuKshWv4vARoZatz6mlQ0JxURH0Kv5+zNeJKJCa8= github.com/google/gnostic-models v0.7.1 h1:SisTfuFKJSKM5CPZkffwi6coztzzeYUhc3v4yxLWH8c= github.com/google/gnostic-models v0.7.1/go.mod h1:whL5G0m6dmc5cPxKc5bdKdEN3UjI7OUGxBlw57miDrQ= github.com/google/go-cmp v0.2.0/go.mod h1:oXzfMopK8JAjlY9xF4vHSVASa0yLyX7SntLO5aqRK0M= @@ -423,21 +500,28 @@ github.com/google/go-cmp v0.5.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/ github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/go-cmp v0.5.3/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= +github.com/google/go-cmp v0.5.8/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY= github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY= github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8= github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU= +github.com/google/go-github/v57 v57.0.0 h1:L+Y3UPTY8ALM8x+TV0lg+IEBI+upibemtBD8Q9u7zHs= +github.com/google/go-github/v57 v57.0.0/go.mod h1:s0omdnye0hvK/ecLvpsGfJMiRt85PimQh4oygmLIxHw= +github.com/google/go-querystring v1.2.0 h1:yhqkPbu2/OH+V9BfpCVPZkNmUXhb2gBxJArfhIxNtP0= +github.com/google/go-querystring v1.2.0/go.mod h1:8IFJqpSRITyJ8QhQ13bmbeMBDfmeEJZD5A0egEOmkqU= github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg= -github.com/google/jsonschema-go v0.4.2 h1:tmrUohrwoLZZS/P3x7ex0WAVknEkBZM46iALbcqoRA8= -github.com/google/jsonschema-go v0.4.2/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE= +github.com/google/gops v0.3.29 h1:n98J2qSOK1NJvRjdLDcjgDryjpIBGhbaqph1mXKL0rY= +github.com/google/gops v0.3.29/go.mod h1:8N3jZftuPazvUwtYY/ncG4iPrjp15ysNKLfq+QQPiwc= +github.com/google/jsonschema-go v0.4.3 h1:/DBOLZTfDow7pe2GmaJNhltueGTtDKICi8V8p+DQPd0= +github.com/google/jsonschema-go v0.4.3/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE= github.com/google/martian/v3 v3.3.3 h1:DIhPTQrbPkgs2yJYdXU/eNACCG5DVQjySNRNlflZ9Fc= github.com/google/martian/v3 v3.3.3/go.mod h1:iEPrYcgCF7jA9OtScMFQyAlZZ4YXTKEtJ1E6RWzmBA0= -github.com/google/pprof v0.0.0-20260402051712-545e8a4df936 h1:EwtI+Al+DeppwYX2oXJCETMO23COyaKGP6fHVpkpWpg= -github.com/google/pprof v0.0.0-20260402051712-545e8a4df936/go.mod h1:MxpfABSjhmINe3F1It9d+8exIHFvUqtLIRCdOGNXqiI= +github.com/google/pprof v0.0.0-20260507013755-92041b743c96 h1:YDDnaZ9afWajDboPMt9Vikqca/yWAX7KAxVzb4lJU1M= +github.com/google/pprof v0.0.0-20260507013755-92041b743c96/go.mod h1:MxpfABSjhmINe3F1It9d+8exIHFvUqtLIRCdOGNXqiI= github.com/google/s2a-go v0.1.9 h1:LGD7gtMgezd8a/Xak7mEWL0PjoTQFvpRudN895yqKW0= github.com/google/s2a-go v0.1.9/go.mod h1:YA0Ei2ZQL3acow2O62kdp9UlnvMmU7kA6Eutn0dXayM= github.com/google/uuid v1.1.2/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= -github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0= -github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= +github.com/google/uuid v1.6.1-0.20241114170450-2d3c2a9cc518 h1:UBg1xk+oAsIVbFuGg6hdfAm7EvCv3EL80vFxJNsslqw= +github.com/google/uuid v1.6.1-0.20241114170450-2d3c2a9cc518/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= github.com/google/wire v0.7.0 h1:JxUKI6+CVBgCO2WToKy/nQk0sS+amI9z9EjVmdaocj4= github.com/google/wire v0.7.0/go.mod h1:n6YbUQD9cPKTnHXEBN2DXlOp/mVADhVErcMFb0v3J18= github.com/googleapis/enterprise-certificate-proxy v0.3.17 h1:73NfMHdiqo9JFU9+7a5ExpVa10/R29pXfZIaW559nrg= @@ -492,6 +576,7 @@ github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc= github.com/jinzhu/now v1.1.5 h1:/o9tlHleP7gOFmsnYNz3RGnqzefHA47wQpKrrdTIwXQ= github.com/jinzhu/now v1.1.5/go.mod h1:d3SSVoowX0Lcu0IBviAWJpolVfI5UJVZZ7cO71lE/z8= +github.com/jmespath/go-jmespath v0.4.0/go.mod h1:T8mJZnbsbmF+m6zOOFylbeCJqk5+pHWvzYPziyZiYoo= github.com/jmespath/go-jmespath v0.4.1-0.20220621161143-b0104c826a24 h1:liMMTbpW34dhU4az1GN0pTPADwNmvoRSeoZ6PItiqnY= github.com/jmespath/go-jmespath v0.4.1-0.20220621161143-b0104c826a24/go.mod h1:T8mJZnbsbmF+m6zOOFylbeCJqk5+pHWvzYPziyZiYoo= github.com/jmespath/go-jmespath/internal/testify v1.5.1 h1:shLQSRRSCCPj3f2gpwzGwWFoC7ycTf1rcQZHOlsJ6N8= @@ -547,6 +632,8 @@ github.com/mark3labs/mcp-go v0.56.0 h1:7aCj2wODCskMi08f923ADG+EfELZBdiKILny415cI github.com/mark3labs/mcp-go v0.56.0/go.mod h1:+8WclSK1ZUweCP3hvktSji8n8ABG/95QaEkeVE/Uwas= github.com/maruel/natural v1.1.1 h1:Hja7XhhmvEFhcByqDoHz9QZbkWey+COd9xWfCfn1ioo= github.com/maruel/natural v1.1.1/go.mod h1:v+Rfd79xlw1AgVBjbO0BEQmptqb5HvL/k9GRHB7ZKEg= +github.com/maruel/panicparse/v2 v2.5.0 h1:yCtuS0FWjfd0RTYMXGpDvWcb0kINm8xJGu18/xMUh00= +github.com/maruel/panicparse/v2 v2.5.0/go.mod h1:DA2fDiBk63bKfBf4CVZP9gb4fuvzdPbLDsSI873hweQ= github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE= github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8= github.com/mattn/go-isatty v0.0.22 h1:j8l17JJ9i6VGPUFUYoTUKPSgKe/83EYU2zBC7YNKMw4= @@ -569,8 +656,26 @@ github.com/mitchellh/hashstructure/v2 v2.0.2 h1:vGKWl0YJqUNxE8d+h8f6NJLcCJrgbhC4 github.com/mitchellh/hashstructure/v2 v2.0.2/go.mod h1:MG3aRVU/N29oo/V/IhBX8GR/zz4kQkprJgF2EVszyDE= github.com/mitchellh/reflectwalk v1.0.2 h1:G2LzWKi524PWgd3mLHV8Y5k7s6XUvT0Gef6zxSIeXaQ= github.com/mitchellh/reflectwalk v1.0.2/go.mod h1:mSTlrgnPZtwu0c4WaC2kGObEpuNDbx0jmZXqmk4esnw= +github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3Nl2EsFP0= +github.com/moby/docker-image-spec v1.3.1/go.mod h1:eKmb5VW8vQEh/BAr2yvVNvuiJuY6UIocYsFu/DxxRpo= +github.com/moby/go-archive v0.1.0 h1:Kk/5rdW/g+H8NHdJW2gsXyZ7UnzvJNOy6VKJqueWdcQ= +github.com/moby/go-archive v0.1.0/go.mod h1:G9B+YoujNohJmrIYFBpSd54GTUB4lt9S+xVQvsJyFuo= +github.com/moby/moby/api v1.52.0 h1:00BtlJY4MXkkt84WhUZPRqt5TvPbgig2FZvTbe3igYg= +github.com/moby/moby/api v1.52.0/go.mod h1:8mb+ReTlisw4pS6BRzCMts5M49W5M7bKt1cJy/YbAqc= +github.com/moby/moby/client v0.1.0 h1:nt+hn6O9cyJQqq5UWnFGqsZRTS/JirUqzPjEl0Bdc/8= +github.com/moby/moby/client v0.1.0/go.mod h1:O+/tw5d4a1Ha/ZA/tPxIZJapJRUS6LNZ1wiVRxYHyUE= +github.com/moby/patternmatcher v0.6.0 h1:GmP9lR19aU5GqSSFko+5pRqHi+Ohk1O69aFiKkVGiPk= +github.com/moby/patternmatcher v0.6.0/go.mod h1:hDPoyOpDY7OrrMDLaYoY3hf52gNCR/YOUYxkhApJIxc= github.com/moby/spdystream v0.5.1 h1:9sNYeYZUcci9R6/w7KDaFWEWeV4LStVG78Mpyq/Zm/Y= github.com/moby/spdystream v0.5.1/go.mod h1:xBAYlnt/ay+11ShkdFKNAG7LsyK/tmNBVvVOwrfMgdI= +github.com/moby/sys/sequential v0.6.0 h1:qrx7XFUd/5DxtqcoH1h438hF5TmOvzC/lspjy7zgvCU= +github.com/moby/sys/sequential v0.6.0/go.mod h1:uyv8EUTrca5PnDsdMGXhZe6CCe8U/UiTWd+lL+7b/Ko= +github.com/moby/sys/user v0.4.0 h1:jhcMKit7SA80hivmFJcbB1vqmw//wU61Zdui2eQXuMs= +github.com/moby/sys/user v0.4.0/go.mod h1:bG+tYYYJgaMtRKgEmuueC0hJEAZWwtIbZTB+85uoHjs= +github.com/moby/sys/userns v0.1.0 h1:tVLXkFOxVu9A64/yh59slHVv9ahO9UIev4JZusOLG/g= +github.com/moby/sys/userns v0.1.0/go.mod h1:IHUYgu/kao6N8YZlp9Cf444ySSvCmDlmzUcYfDHOl28= +github.com/moby/term v0.5.2 h1:6qk3FJAFDs6i/q3W/pQ97SX192qKfZgGjCQqfCJkgzQ= +github.com/moby/term v0.5.2/go.mod h1:d3djjFCrjnB+fl8NJux+EJzu0msscUP+f8it8hPkFLc= github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q= github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg= github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q= @@ -608,10 +713,14 @@ github.com/openai/openai-go v1.12.0 h1:NBQCnXzqOTv5wsgNC36PrFEiskGfO5wccfCWDo9S1 github.com/openai/openai-go v1.12.0/go.mod h1:g461MYGXEXBVdV5SaR/5tNzNbSfwTBBefwc+LlDCK0Y= github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8Oi/yOhh5U= github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM= +github.com/opencontainers/image-spec v1.1.1 h1:y0fUlFfIZhPF1W537XOLg0/fcx6zcHCJwooC2xJA040= +github.com/opencontainers/image-spec v1.1.1/go.mod h1:qpqAh3Dmcf36wStyyWU+kCeDgrGnAve2nCC8+7h8Q0M= +github.com/opensearch-project/opensearch-go/v2 v2.3.0 h1:nQIEMr+A92CkhHrZgUhcfsrZjibvB3APXf2a1VwCmMQ= +github.com/opensearch-project/opensearch-go/v2 v2.3.0/go.mod h1:8LDr9FCgUTVoT+5ESjc2+iaZuldqE+23Iq0r1XeNue8= github.com/orcaman/concurrent-map/v2 v2.0.1 h1:jOJ5Pg2w1oeB6PeDurIYf6k9PQ+aTITr/6lP/L/zp6c= github.com/orcaman/concurrent-map/v2 v2.0.1/go.mod h1:9Eq3TG2oBe5FirmYWQfYO5iH1q0Jv47PLaNK++uCdOM= -github.com/patrickmn/go-cache v2.1.0+incompatible h1:HRMgzkcYKYpi3C8ajMPV8OFXaaRUnok+kx1WdO15EQc= -github.com/patrickmn/go-cache v2.1.0+incompatible/go.mod h1:3Qf8kWWT7OJRJbdiICTKqZju1ZixQ/KpMGzzAfe6+WQ= +github.com/patrickmn/go-cache v2.1.1-0.20191004192108-46f407853014+incompatible h1:IWzUvJ72xMjmrjR9q3H1PF+jwdN0uNQiR2t1BLNalyo= +github.com/patrickmn/go-cache v2.1.1-0.20191004192108-46f407853014+incompatible/go.mod h1:3Qf8kWWT7OJRJbdiICTKqZju1ZixQ/KpMGzzAfe6+WQ= github.com/paulmach/orb v0.12.0 h1:z+zOwjmG3MyEEqzv92UN49Lg1JFYx0L9GpGKNVDKk1s= github.com/paulmach/orb v0.12.0/go.mod h1:5mULz1xQfs3bmQm63QEJA6lNGujuRafwA5S/EnuLaLU= github.com/paulmach/protoscan v0.2.1/go.mod h1:SpcSwydNLrxUGSDvXvO0P7g7AuhJ7lcKfDlhJCDw2gY= @@ -634,8 +743,8 @@ github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4= github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0= github.com/pkg/sftp v1.13.10 h1:+5FbKNTe5Z9aspU88DPIKJ9z2KZoaGCu6Sr6kKR/5mU= github.com/pkg/sftp v1.13.10/go.mod h1:bJ1a7uDhrX/4OII+agvy28lzRvQrmIQuaHrcI1HbeGA= -github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10 h1:GFCKgmp0tecUJ0sJuv4pzYCqS9+RGSn52M3FUwPs+uo= -github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10/go.mod h1:t/avpk3KcrXxUnYOhZhMXJlSEyie6gQbtLq5NM3loB8= +github.com/planetscale/vtprotobuf v0.6.1-0.20250313105119-ba97887b0a25 h1:S1hI5JiKP7883xBzZAr1ydcxrKNSVNm7+3+JwjxZEsg= +github.com/planetscale/vtprotobuf v0.6.1-0.20250313105119-ba97887b0a25/go.mod h1:ZQntvDG8TkPgljxtA0R9frDoND4QORU1VXz015N5Ks4= github.com/pmezard/go-difflib v0.0.0-20151028094244-d8ed2627bdf0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U= @@ -716,6 +825,7 @@ github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/ github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU= github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4= +github.com/stretchr/testify v1.8.2/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4= github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U= github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U= github.com/t14raptor/go-fast v0.1.0 h1:KqwQE+MNvC1NKhoAacqP87NrNOFavvWSP2m6BtCXxsk= @@ -746,6 +856,8 @@ github.com/ugorji/go/codec v1.3.1 h1:waO7eEiFDwidsBN6agj1vJQ4AG7lh2yqXyOXqhgQuyY github.com/ugorji/go/codec v1.3.1/go.mod h1:pRBVtBSKl77K30Bv8R2P+cLSGaTtex6fsA2Wjqmfxj4= github.com/ulikunitz/xz v0.5.15 h1:9DNdB5s+SgV3bQ2ApL10xRc35ck0DuIX/isZvIk+ubY= github.com/ulikunitz/xz v0.5.15/go.mod h1:nbz6k7qbPmH4IRqmfOplQw/tblSgqTqBwxkY0oWt/14= +github.com/valkey-io/valkey-go v1.0.75 h1:cfq9DODW2ntuUgyHJmFWb4/p+xpLpQB1t5SQyWM9uJ4= +github.com/valkey-io/valkey-go v1.0.75/go.mod h1:6X581PhgfeMkJmyfjIsa2eFdq6dy3Qkkg9zwjM1p42M= github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6KllzawFIhcdPw= github.com/valyala/bytebufferpool v1.0.0/go.mod h1:6bBcMArwyJ5K/AmCkWv1jt77kVWyCJ6HpOuEn7z0Csc= github.com/valyala/fasttemplate v1.2.2 h1:lxLXG0uE3Qnshl9QyaK6XJxMXlQZELvChBOCmQD0Loo= @@ -788,6 +900,10 @@ github.com/zclconf/go-cty-debug v0.0.0-20240509010212-0d6042c53940 h1:4r45xpDWB6 github.com/zclconf/go-cty-debug v0.0.0-20240509010212-0d6042c53940/go.mod h1:CmBdvvj3nqzfzJ6nTCIwDTPZ56aVGvDrmztiO5g3qrM= github.com/zclconf/go-cty-yaml v1.2.0 h1:GDyL4+e/Qe/S0B7YaecMLbVvAR/Mp21CXMOSiCTOi1M= github.com/zclconf/go-cty-yaml v1.2.0/go.mod h1:9YLUH4g7lOhVWqUbctnVlZ5KLpg7JAprQNgxSZ1Gyxs= +github.com/zeebo/assert v1.3.0 h1:g7C04CbJuIDKNPFHmsk4hwZDO5O+kntRxzaUoNXj+IQ= +github.com/zeebo/assert v1.3.0/go.mod h1:Pq9JiuJQpG8JLJdtkwrJESF0Foym2/D9XMU5ciN/wJ0= +github.com/zeebo/xxh3 v1.1.0 h1:s7DLGDK45Dyfg7++yxI0khrfwq9661w9EN78eP/UZVs= +github.com/zeebo/xxh3 v1.1.0/go.mod h1:IisAie1LELR4xhVinxWS5+zf1lA4p0MW4T+w+W07F5s= go.mongodb.org/mongo-driver v1.11.4/go.mod h1:PTSz5yu21bkT/wXpkS7WR5f0ddqw5quethTUn9WM+2g= go.opencensus.io v0.24.0 h1:y73uSU6J157QMP2kn2r30vwW1A2W2WFwSCGnAVxeaD0= go.opencensus.io v0.24.0/go.mod h1:vNK8G9p7aAivkbmorf4v+7Hgx+Zs0yY+0fOtgBfjQKo= @@ -874,7 +990,9 @@ golang.org/x/net v0.0.0-20201110031124-69a78807bb2b/go.mod h1:sp8m0HH+o8qH0wwXwY golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg= golang.org/x/net v0.0.0-20211112202133-69e39bad7dc2/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y= golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c= +golang.org/x/net v0.1.0/go.mod h1:Cx3nUiGt4eDBEyega/BKRp+/AlGL8hYe7U9odMt2Cco= golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs= +golang.org/x/net v0.7.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs= golang.org/x/net v0.10.0/go.mod h1:0qNGK6F8kojg2nk9dLZ2mShWaEBan6FAoqfSigmmuDg= golang.org/x/net v0.15.0/go.mod h1:idbUs1IY1+zTqbi8yxTbhexhEEk5ur9LInksu6HrEpk= golang.org/x/net v0.21.0/go.mod h1:bIjVDfnllIU7BJ2DNgfnXvpSvtn8VRwhlsaeUTyUS44= @@ -924,8 +1042,11 @@ golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA= golang.org/x/sys v0.46.0 h1:noSf2Fq6F8DBgS+LysIkx7rIExoNHJsxOAtPp4rthXw= golang.org/x/sys v0.46.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw= golang.org/x/telemetry v0.0.0-20240228155512-f48c80bd79b2/go.mod h1:TeRTkGYfJXctD9OcfyVLyj2J3IxLnKwHJR8f4D8a3YE= +golang.org/x/telemetry v0.0.0-20260625142307-59b4966ccb57 h1:nwGZBCt+FnXUrGsj5vjzAsEmkcaFvd82BbOjECiFYZc= +golang.org/x/telemetry v0.0.0-20260625142307-59b4966ccb57/go.mod h1:3AWMyWHS+caVoiEXpiq6+tzKA40J4vQT3MYr80ZtQpc= golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo= golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8= +golang.org/x/term v0.1.0/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8= golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k= golang.org/x/term v0.8.0/go.mod h1:xPskH00ivmX89bAKVGSKKtLOWNx2+17Eiy94tnKShWo= golang.org/x/term v0.12.0/go.mod h1:owVbMEjm3cBLCHdkQu9b1opXd4ETQWc3BhuQGKgXgvU= @@ -938,6 +1059,7 @@ golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ= golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ= golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ= golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ= +golang.org/x/text v0.4.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8= golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8= golang.org/x/text v0.9.0/go.mod h1:e1OnstbJyHTd6l/uOt8jFFHp6TRDWZR/bV3emEE/zU8= golang.org/x/text v0.13.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE= @@ -1039,14 +1161,14 @@ gotest.tools/v3 v3.5.2 h1:7koQfIKdy+I8UTetycgUqXWSDwpgv193Ka+qRsmBY8Q= gotest.tools/v3 v3.5.2/go.mod h1:LtdLGcnqToBH83WByAAi/wiwSFCArdFIUV/xxN4pcjA= honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4= honnef.co/go/tools v0.0.0-20190523083050-ea95bdfd59fc/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4= -k8s.io/api v0.36.1 h1:XbL/EMj8K2aJpJtePmqUyQMsM0D4QI2pvl7YKJ20FTY= -k8s.io/api v0.36.1/go.mod h1:KOWo4ey3TINlXjeHVuwB3i+tXXnu+UcwFBHlI/9dvEo= -k8s.io/apiextensions-apiserver v0.36.1 h1:6JfYmPUsuUIHuN+3QxutXYWj492RqF5fBSx67GYK5Ks= -k8s.io/apiextensions-apiserver v0.36.1/go.mod h1:pLzZin90riwisdzKwv/GoTwENooytoIx5zWJb4Hkby8= +k8s.io/api v0.36.2 h1:TF6YDLIzKfccK7cq9YpTcGX8TJmEkHVRv78DM51fRYY= +k8s.io/api v0.36.2/go.mod h1:F4LbMO4brjZYh7yFkXWhynSvtB7YauxV4c+HHkNRGNg= +k8s.io/apiextensions-apiserver v0.36.2 h1:3O5gqOj/dt2XWWbpMe+TXWpE9yU6pjM/tXxtHHJT/K4= +k8s.io/apiextensions-apiserver v0.36.2/go.mod h1:cL1tBWe8XSaP1H30iWKGo7hf6iAUUUJPEU70dskmAnA= k8s.io/apimachinery v0.36.2 h1:0PE/W/WNy1UX61NLbXY5TMbJ6UwLL6E6lAPkYrKFxbQ= k8s.io/apimachinery v0.36.2/go.mod h1:fvf/HOLXq9RId0rnDIbN1OEBvHXdQbLMM8nu0LcBUf4= -k8s.io/client-go v0.36.1 h1:FN/K8QIT2CEDt+2WB2HnWrUANZ50AP5GII43/SP2JR0= -k8s.io/client-go v0.36.1/go.mod h1:s6rAnCtTGYDQnpNjEhSaISV+2O8jwruZ6m3QOYBFbtU= +k8s.io/client-go v0.36.2 h1:bfgxmFKc9CgqsgX4xKLAAdmTQlWee7Ob/HlDOrJ5TBI= +k8s.io/client-go v0.36.2/go.mod h1:1vgO4OAlfPnoLcb+Rze2GF5rAr14w8qjrYMoyXJzQj0= k8s.io/klog/v2 v2.140.0 h1:Tf+J3AH7xnUzZyVVXhTgGhEKnFqye14aadWv7bzXdzc= k8s.io/klog/v2 v2.140.0/go.mod h1:o+/RWfJ6PwpnFn7OyAG3QnO47BFsymfEfrz6XyYSSp0= k8s.io/kube-openapi v0.0.0-20260317180543-43fb72c5454a h1:xCeOEAOoGYl2jnJoHkC3hkbPJgdATINPMAxaynU2Ovg= diff --git a/pkg/ai/prompt/validate.go b/pkg/ai/prompt/validate.go new file mode 100644 index 00000000..2b99d44b --- /dev/null +++ b/pkg/ai/prompt/validate.go @@ -0,0 +1,185 @@ +package prompt + +import ( + "fmt" + "math" + "regexp" + "strconv" + "strings" + + "github.com/flanksource/captain/pkg/api" + "github.com/mbleigh/raymond" + "github.com/mbleigh/raymond/parser" + "gopkg.in/yaml.v3" +) + +type ValidationOptions struct { + Data map[string]any +} + +type Diagnostic struct { + Rule string + Severity string + Message string + Line int + Column int +} + +var ( + frontmatterOpening = regexp.MustCompile(`^(?:(?:#[^\n]*|[ \t]*)\n)*---[ \t]*(?:\r?\n|$)`) + diagnosticLine = regexp.MustCompile(`(?i)line[: ]+([0-9]+)`) + diagnosticField = regexp.MustCompile(`field ([^ ]+) not found`) +) + +// Validate checks authored declarations without executing the body or resolving runtime configuration. +func (t *Template) Validate(options ValidationOptions) []Diagnostic { + frontmatter, body, hasFrontmatter := splitFrontmatter(t.source) + if !hasFrontmatter && frontmatterOpening.MatchString(t.source) { + return []Diagnostic{{Rule: "promptfile/frontmatter", Severity: "error", Message: "frontmatter is missing its closing --- delimiter", Line: 1}} + } + var diagnostics []Diagnostic + bodyOffset := strings.Count(t.source[:len(t.source)-len(body)], "\n") + if _, err := raymond.Parse(body); err != nil { + diagnostics = append(diagnostics, validationError("promptfile/template", err, bodyOffset)) + } + if !hasFrontmatter || strings.TrimSpace(frontmatter) == "" { + return diagnostics + } + loc := frontmatterRe.FindStringSubmatchIndex(t.source) + frontmatterOffset := strings.Count(t.source[:loc[2]], "\n") + program, err := parser.Parse(frontmatter) + if err != nil { + return append(diagnostics, validationError("promptfile/template", err, frontmatterOffset)) + } + missing := missingFrontmatterVariables(program, options.Data) + if len(missing) > 0 { + return append(diagnostics, Diagnostic{Rule: "promptfile/variables", Severity: "warning", Line: frontmatterOffset + 1, + Message: "frontmatter declaration checks deferred; supply --var or --vars for: " + strings.Join(missing, ", ")}) + } + source, err := renderFrontmatter(t.source, options.Data) + if err != nil { + return append(diagnostics, validationError("promptfile/frontmatter", err, frontmatterOffset)) + } + declarations := validateDeclarations(source) + if source != t.source { + for i := range declarations { + declarations[i].Line, declarations[i].Column = 0, 0 + declarations[i].Message = "rendered frontmatter: " + declarations[i].Message + } + } + return append(diagnostics, declarations...) +} + +func validateDeclarations(source string) []Diagnostic { + frontmatter, _, _ := splitFrontmatter(source) + if strings.TrimSpace(frontmatter) == "" { + return nil + } + loc := frontmatterRe.FindStringSubmatchIndex(source) + offset := strings.Count(source[:loc[2]], "\n") + document, err := Parse(source) + if err != nil { + diagnostic := validationError("promptfile/frontmatter", err, offset) + if field := diagnosticField.FindStringSubmatch(err.Error()); field != nil { + diagnostic.Line, diagnostic.Column = declarationPosition(frontmatter, field[1]) + if diagnostic.Line > 0 { + diagnostic.Line += offset + } + } + return []Diagnostic{diagnostic} + } + var diagnostics []Diagnostic + for _, warning := range document.Warnings { + diagnostics = append(diagnostics, Diagnostic{Rule: "promptfile/deprecation", Severity: "warning", Message: warning}) + } + if err := validateDeclaredSpec(document); err != nil { + diagnostics = append(diagnostics, validationError("promptfile/spec", err, 0)) + } + if _, err := Load(source).Hook(); err != nil { + diagnostics = append(diagnostics, validationError("promptfile/hook", err, offset)) + } + if err := validateSchemaSections(document.Frontmatter); err != nil { + diagnostics = append(diagnostics, validationError("promptfile/schema", err, offset)) + } else if err := validateDeclaredSchemas(source); err != nil { + diagnostics = append(diagnostics, validationError("promptfile/schema", err, offset)) + } + return diagnostics +} + +func validateDeclaredSpec(document *Document) error { + if config, ok := document.Frontmatter["config"]; ok { + values, ok := config.(map[string]any) + if !ok { + return fmt.Errorf("config must be a mapping") + } + if err := validateDotpromptConfig(values); err != nil { + return err + } + applyModelConfig(values, &document.Spec) + } + if err := document.Spec.ValidateStructure(); err != nil { + return err + } + for i, model := range document.Runtimes { + if err := (api.Spec{Model: model}).ValidateStructure(); err != nil { + return fmt.Errorf("runtime %d: %w", i+1, err) + } + } + return nil +} + +func validateDotpromptConfig(values map[string]any) error { + for _, key := range []string{"maxOutputTokens", "temperature"} { + if value, exists := values[key]; exists { + number, ok := floatOf(value) + if !ok { + return fmt.Errorf("config.%s must be a number", key) + } + if math.IsNaN(number) || math.IsInf(number, 0) { + return fmt.Errorf("config.%s must be finite", key) + } + if key == "maxOutputTokens" && (math.Trunc(number) != number || number >= float64(int(^uint(0)>>1))) { + return fmt.Errorf("config.maxOutputTokens must be an integer within the supported range") + } + } + } + if value, exists := values["reasoning"]; exists { + if _, ok := value.(string); !ok { + return fmt.Errorf("config.reasoning must be a string") + } + } + return nil +} + +func validationError(rule string, err error, offset int) Diagnostic { + diagnostic := Diagnostic{Rule: rule, Severity: "error", Message: err.Error()} + if match := diagnosticLine.FindStringSubmatch(err.Error()); match != nil { + diagnostic.Line, _ = strconv.Atoi(match[1]) + diagnostic.Line += offset + } + return diagnostic +} + +func declarationPosition(source, field string) (int, int) { + var root yaml.Node + if err := yaml.Unmarshal([]byte(source), &root); err != nil { + return 0, 0 + } + var visit func(*yaml.Node) (int, int) + visit = func(node *yaml.Node) (int, int) { + if node.Kind == yaml.MappingNode { + for i := 0; i < len(node.Content); i += 2 { + if node.Content[i].Value == field { + return node.Content[i].Line, node.Content[i].Column + } + } + } + for _, child := range node.Content { + if line, column := visit(child); line > 0 { + return line, column + } + } + return 0, 0 + } + return visit(&root) +} diff --git a/pkg/ai/prompt/validate_ginkgo_test.go b/pkg/ai/prompt/validate_ginkgo_test.go new file mode 100644 index 00000000..db564bba --- /dev/null +++ b/pkg/ai/prompt/validate_ginkgo_test.go @@ -0,0 +1,102 @@ +package prompt + +import ( + "os" + + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("Prompt validation", func() { + DescribeTable("reports invalid declarations without executing a prompt", + func(source, rule, message string) { + diagnostics := LoadNamed("review.prompt", source).Validate(ValidationOptions{}) + Expect(diagnostics).To(ContainElement(And( + HaveField("Rule", rule), HaveField("Severity", "error"), + HaveField("Message", ContainSubstring(message)), + ))) + }, + Entry("unclosed frontmatter", "---\nmodel: sonnet\n", "promptfile/frontmatter", "closing"), + Entry("malformed YAML", "---\nmodel: [unfinished\n---\nbody\n", "promptfile/frontmatter", "yaml"), + Entry("duplicate YAML key", "---\neffort: low\neffort: high\n---\nbody\n", "promptfile/frontmatter", "already defined"), + Entry("unknown field", "---\nmaxTruns: 2\n---\nbody\n", "promptfile/frontmatter", "maxTruns"), + Entry("invalid option", "---\ntemperature: 9\n---\nbody\n", "promptfile/spec", "temperature"), + Entry("invalid dotprompt option", "---\nconfig:\n temperature: 9\n---\nbody\n", "promptfile/spec", "temperature"), + Entry("non-numeric dotprompt option", "---\nconfig:\n temperature: warm\n---\nbody\n", "promptfile/spec", "number"), + Entry("fractional output-token limit", "---\nconfig:\n maxOutputTokens: 1.5\n---\nbody\n", "promptfile/spec", "integer"), + Entry("non-finite temperature", "---\nconfig:\n temperature: .nan\n---\nbody\n", "promptfile/spec", "finite"), + Entry("invalid compact runtime declaration", "---\nruntimes: [\"agent:sonnet:invalid\", \"agent:sonnet\"]\n---\nbody\n", "promptfile/frontmatter", "effort"), + Entry("invalid runtime option", "---\nruntimes: [{model: sonnet, temperature: 9}, {model: sonnet}]\n---\nbody\n", "promptfile/spec", "temperature"), + Entry("invalid body template", "{{#if enabled}}\nReview {{name}}\n", "promptfile/template", "Parse error"), + Entry("invalid frontmatter template", "---\n{{#if enabled}}\nmodel: sonnet\n---\nbody\n", "promptfile/template", "Parse error"), + Entry("invalid hook", "---\nhook: {on: plan.revision, mode: invalid}\n---\nbody\n", "promptfile/hook", "mode"), + Entry("invalid schema declaration", "---\noutput: {schemaType: invalid}\n---\nbody\n", "promptfile/schema", "schema type"), + Entry("invalid JSON Schema", "---\noutput:\n schema:\n type: invalid\n---\nbody\n", "promptfile/schema", "invalid"), + Entry("invalid schema shape", "---\noutput: {schema: 42}\n---\nbody\n", "promptfile/schema", "schema"), + Entry("unknown schema field", "---\noutput: {scheam: {answer: string}}\n---\nbody\n", "promptfile/schema", "scheam"), + Entry("invalid input defaults", "---\ninput: {default: 42}\n---\nbody\n", "promptfile/schema", "default"), + Entry("invalid TypeSafe questions", "---\noutput:\n schemaType: typesafe-schema\n schema:\n review: {type: choice}\n---\nbody\n", "promptfile/schema", "review"), + ) + + DescribeTable("accepts reusable declarations without runtime configuration", + func(source string) { + Expect(Load(source).Validate(ValidationOptions{})).To(BeEmpty()) + }, + Entry("body variables", "{{role \"user\"}}\nReview {{missing}}\n"), + Entry("body-only", "Review this change.\n"), + Entry("empty frontmatter", "---\n---\nReview {{missing}}\n"), + Entry("preset-only", "---\npresets: [reviewer]\n---\n"), + Entry("custom model", "---\nmodel: tenant-review-model\nmode: api\n---\nReview {{missing}}\n"), + Entry("picoschema", "---\noutput:\n schema:\n answer: string\n---\nReview.\n"), + Entry("JSON Schema", "---\noutput:\n schema: {type: object, properties: {answer: {type: string}}}\n---\nReview.\n"), + Entry("disabled hook", "---\nhook: {disabled: true}\n---\n"), + ) + + It("warns with the missing frontmatter variables and still checks the body", func() { + const source = "---\nmodel: {{model}}\nbudget:\n maxTokens: {{limit}}\n---\n{{#if broken}}\n" + diagnostics := Load(source).Validate(ValidationOptions{Data: map[string]any{"model": "sonnet"}}) + Expect(diagnostics).To(ContainElement(And(HaveField("Rule", "promptfile/variables"), HaveField("Severity", "warning"), HaveField("Message", ContainSubstring("limit"))))) + Expect(diagnostics).To(ContainElement(HaveField("Rule", "promptfile/template"))) + }) + + It("validates rendered declarations with complete inputs", func() { + const source = "---\nbudget:\n maxTokens: {{limit}}\n---\nReview {{bodyOnly}}\n" + Expect(Load(source).Validate(ValidationOptions{Data: map[string]any{"limit": 100}})).To(BeEmpty()) + diagnostics := Load(source).Validate(ValidationOptions{Data: map[string]any{"limit": "[unfinished"}}) + Expect(diagnostics).To(ContainElement(HaveField("Rule", "promptfile/frontmatter"))) + }) + + It("reports nested missing inputs instead of rendering empty values", func() { + const source = "---\nbudget:\n maxTokens: {{options.limit}}\n---\nReview.\n" + diagnostics := Load(source).Validate(ValidationOptions{Data: map[string]any{"options": map[string]any{}}}) + Expect(diagnostics).To(ContainElement(HaveField("Message", ContainSubstring("options.limit")))) + }) + + It("checks templated conditional schemas with supplied values", func() { + Expect(Load(templatedSchemaPrompt).Validate(ValidationOptions{Data: map[string]any{"limit": 3}})).To(BeEmpty()) + Expect(Load(templatedSchemaPrompt).Validate(ValidationOptions{})).To(ContainElement(HaveField("Severity", "warning"))) + }) + + It("supports TypeSafe declarations using the real reusable fixture", func() { + source, err := os.ReadFile("testdata/fixtures/jev.prompt") + Expect(err).NotTo(HaveOccurred()) + Expect(Load(string(source)).Validate(ValidationOptions{})).To(BeEmpty()) + }) + + It("reports YAML positions in the original source", func() { + const source = "# review\n---\nmodel: sonnet\nmaxTruns: 2\n---\nReview.\n" + diagnostics := Load(source).Validate(ValidationOptions{}) + Expect(diagnostics).To(ContainElement(And(HaveField("Rule", "promptfile/frontmatter"), HaveField("Line", 4)))) + }) + + DescribeTable("resolves frontmatter variables in conditional and scoped expressions", + func(frontmatter string, data map[string]any) { + Expect(Load("---\n" + frontmatter + "---\nbody\n").Validate(ValidationOptions{Data: data})).To(BeEmpty()) + }, + Entry("inactive branch", "{{#if enabled}}\nbudget:\n maxTokens: {{missing}}\n{{/if}}\n", map[string]any{"enabled": false}), + Entry("with scope", "{{#with limits}}\nbudget:\n maxTokens: {{tokens}}\n{{/with}}\n", map[string]any{"limits": map[string]any{"tokens": 100}}), + Entry("with alias", "{{#with limits as |values|}}\nbudget:\n maxTokens: {{values.tokens}}\n{{/with}}\n", map[string]any{"limits": map[string]any{"tokens": 100}}), + Entry("each alias and root", "runtimes:\n{{#each names as |name|}}\n - model: {{name}}\n effort: {{@root.effort}}\n{{/each}}\n", map[string]any{"names": []string{"sonnet", "opus"}, "effort": "low"}), + Entry("lookup condition", "{{#if (lookup flags \"enabled\")}}\nbudget:\n maxTokens: {{missing}}\n{{/if}}\n", map[string]any{"flags": map[string]any{"enabled": false}}), + ) +}) diff --git a/pkg/ai/prompt/validate_schema.go b/pkg/ai/prompt/validate_schema.go new file mode 100644 index 00000000..6bc6b4b6 --- /dev/null +++ b/pkg/ai/prompt/validate_schema.go @@ -0,0 +1,84 @@ +package prompt + +import ( + "bytes" + "encoding/json" + "fmt" + "slices" + + dp "github.com/google/dotprompt/go/dotprompt" + "github.com/santhosh-tekuri/jsonschema/v6" +) + +func validateSchemaSections(frontmatter map[string]any) error { + for _, name := range []string{"input", "output"} { + section, err := schemaSection(frontmatter, name) + if err != nil { + return err + } + allowed := []string{"schemaType", "schema", "format"} + if name == "input" { + allowed = []string{"schemaType", "schema", "default"} + } + for key := range section { + if !slices.Contains(allowed, key) { + return fmt.Errorf("unknown %s field %q", name, key) + } + } + if schema, exists := section["schema"]; exists { + switch schema.(type) { + case string, map[string]any: + default: + return fmt.Errorf("%s.schema must be a mapping or Picoschema string", name) + } + } + if defaults, exists := section["default"]; exists { + if _, ok := defaults.(map[string]any); !ok { + return fmt.Errorf("input.default must be a mapping") + } + } + if format, exists := section["format"]; exists { + if _, ok := format.(string); !ok { + return fmt.Errorf("output.format must be a string") + } + } + } + return nil +} + +func validateDeclaredSchemas(source string) error { + prepared, _, err := PrepareSchemaSource(source) + if err != nil { + return err + } + metadata, err := dp.NewDotprompt(nil).RenderMetadata(prepared, nil) + if err != nil { + return err + } + for _, section := range []struct { + name string + schema dp.Schema + }{{"input", metadata.Input.Schema}, {"output", metadata.Output.Schema}} { + if section.schema == nil { + continue + } + raw, err := json.Marshal(section.schema) + if err != nil { + return fmt.Errorf("%s.schema: %w", section.name, err) + } + decoded, err := jsonschema.UnmarshalJSON(bytes.NewReader(raw)) + if err != nil { + return fmt.Errorf("%s.schema: %w", section.name, err) + } + compiler := jsonschema.NewCompiler() + compiler.UseLoader(jsonschema.SchemeURLLoader{}) + resource := "mem:///captain/prompt/" + section.name + ".json" + if err := compiler.AddResource(resource, decoded); err != nil { + return fmt.Errorf("%s.schema: %w", section.name, err) + } + if _, err := compiler.Compile(resource); err != nil { + return fmt.Errorf("%s.schema: %w", section.name, err) + } + } + return nil +} diff --git a/pkg/ai/prompt/validate_variables.go b/pkg/ai/prompt/validate_variables.go new file mode 100644 index 00000000..2638b1ee --- /dev/null +++ b/pkg/ai/prompt/validate_variables.go @@ -0,0 +1,243 @@ +package prompt + +import ( + "reflect" + "slices" + "strconv" + "strings" + + "github.com/mbleigh/raymond" + "github.com/mbleigh/raymond/ast" +) + +type variableScope struct { + value any + aliases map[string]any + data map[string]any +} + +type variableCheck struct { + scopes []variableScope + missing map[string]bool +} + +func missingFrontmatterVariables(program *ast.Program, data map[string]any) []string { + check := variableCheck{scopes: []variableScope{{value: data}}, missing: map[string]bool{}} + check.visit(program) + missing := make([]string, 0, len(check.missing)) + for name := range check.missing { + missing = append(missing, name) + } + slices.Sort(missing) + return missing +} + +func (c *variableCheck) visit(node ast.Node) { + switch node := node.(type) { + case *ast.Program: + if node != nil { + for _, child := range node.Body { + c.visit(child) + } + } + case *ast.MustacheStatement: + c.visit(node.Expression) + case *ast.Expression: + if len(node.Params) == 0 && node.Hash == nil { + c.visit(node.Path) + } + for _, param := range node.Params { + c.visit(param) + } + if node.Hash != nil { + for _, pair := range node.Hash.Pairs { + c.visit(pair.Val) + } + } + case *ast.SubExpression: + c.visit(node.Expression) + case *ast.PathExpression: + if _, exists := c.value(node); !exists { + c.missing[node.Original] = true + } + case *ast.BlockStatement: + c.visitBlock(node) + case *ast.PartialStatement: + for _, param := range node.Params { + c.visit(param) + } + } +} + +func (c *variableCheck) visitBlock(block *ast.BlockStatement) { + c.visit(block.Expression) + if len(block.Expression.Params) == 0 { + c.visit(block.Program) + c.visit(block.Inverse) + return + } + value, known := c.value(block.Expression.Params[0]) + if !known { + c.visit(block.Program) + c.visit(block.Inverse) + return + } + switch block.Expression.HelperName() { + case "if", "unless": + truth := raymond.IsTrue(value) + if block.Expression.HelperName() == "unless" { + truth = !truth + } + if truth { + c.visit(block.Program) + } else { + c.visit(block.Inverse) + } + case "with": + if raymond.IsTrue(value) { + aliases := map[string]any{} + if len(block.Program.BlockParams) > 0 { + aliases[block.Program.BlockParams[0]] = value + } + c.visitScope(block.Program, variableScope{value: value, aliases: aliases}) + } else { + c.visit(block.Inverse) + } + case "each": + c.visitEach(block, value) + default: + c.visit(block.Program) + c.visit(block.Inverse) + } +} + +func (c *variableCheck) visitEach(block *ast.BlockStatement, value any) { + items := reflect.ValueOf(value) + if !items.IsValid() || (items.Kind() != reflect.Map && items.Kind() != reflect.Slice && items.Kind() != reflect.Array) || items.Len() == 0 { + c.visit(block.Inverse) + return + } + var keys []reflect.Value + if items.Kind() == reflect.Map { + keys = items.MapKeys() + } + for i := 0; i < items.Len(); i++ { + var item, key any + if items.Kind() == reflect.Map { + mapKey := keys[i] + key, item = mapKey.Interface(), items.MapIndex(mapKey).Interface() + } else { + key, item = i, items.Index(i).Interface() + } + aliases := map[string]any{} + for j, name := range block.Program.BlockParams { + if j == 0 { + aliases[name] = item + } else { + aliases[name] = key + } + } + data := map[string]any{"index": i, "key": key, "first": i == 0, "last": i == items.Len()-1} + c.visitScope(block.Program, variableScope{value: item, aliases: aliases, data: data}) + } +} + +func (c *variableCheck) visitScope(program *ast.Program, scope variableScope) { + c.scopes = append(c.scopes, scope) + c.visit(program) + c.scopes = c.scopes[:len(c.scopes)-1] +} + +func (c *variableCheck) value(node ast.Node) (any, bool) { + switch node := node.(type) { + case *ast.PathExpression: + return c.pathValue(node) + case *ast.StringLiteral: + return node.Value, true + case *ast.BooleanLiteral: + return node.Value, true + case *ast.NumberLiteral: + return node.Number(), true + case *ast.SubExpression: + if node.Expression.HelperName() == "lookup" && len(node.Expression.Params) == 2 { + value, valueKnown := c.value(node.Expression.Params[0]) + key, keyKnown := c.value(node.Expression.Params[1]) + if valueKnown && keyKnown { + return variableProperty(value, raymond.Str(key)) + } + } + return nil, false + default: + return nil, false + } +} + +func (c *variableCheck) pathValue(path *ast.PathExpression) (any, bool) { + index := len(c.scopes) - 1 - path.Depth + parts := path.Parts + if path.Data { + if len(parts) > 0 && parts[0] == "root" { + index, parts = 0, parts[1:] + } else { + for i := index; i >= 0; i-- { + if value, exists := c.scopes[i].data[strings.Join(parts, ".")]; exists { + return value, true + } + } + return nil, false + } + } + if index < 0 { + return nil, false + } + value := c.scopes[index].value + if len(parts) > 0 { + for i := index; i >= 0; i-- { + if alias, exists := c.scopes[i].aliases[parts[0]]; exists { + value, parts = alias, parts[1:] + break + } + } + } + for _, part := range parts { + var exists bool + value, exists = variableProperty(value, part) + if !exists { + return nil, false + } + } + return value, true +} + +func variableProperty(value any, name string) (any, bool) { + v := reflect.ValueOf(value) + for v.IsValid() && (v.Kind() == reflect.Interface || v.Kind() == reflect.Pointer) { + v = v.Elem() + } + if !v.IsValid() { + return nil, false + } + switch v.Kind() { + case reflect.Map: + key := reflect.ValueOf(name) + if key.Type().AssignableTo(v.Type().Key()) { + v = v.MapIndex(key) + } else { + return nil, false + } + case reflect.Slice, reflect.Array: + index, err := strconv.Atoi(name) + if err != nil || index < 0 || index >= v.Len() { + return nil, false + } + v = v.Index(index) + case reflect.Struct: + v = v.FieldByName(name) + default: + return nil, false + } + if !v.IsValid() || !v.CanInterface() { + return nil, false + } + return v.Interface(), true +} diff --git a/pkg/cli/prompt_render.go b/pkg/cli/prompt_render.go index 2781a8df..9c851dc6 100644 --- a/pkg/cli/prompt_render.go +++ b/pkg/cli/prompt_render.go @@ -102,7 +102,7 @@ func renderPromptCLI(ctx context.Context, id string, opts AIPromptOptions, varsJ if err != nil { return PromptRenderResult{}, err } - vars, err := promptVars(opts, varsJSON, stdin, body.UsedStdin) + vars, err := ParsePromptVariables(opts, varsJSON, stdin, body.UsedStdin) if err != nil { return PromptRenderResult{}, err } diff --git a/pkg/cli/prompt_source.go b/pkg/cli/prompt_source.go index 471552d2..6a6538a8 100644 --- a/pkg/cli/prompt_source.go +++ b/pkg/cli/prompt_source.go @@ -184,14 +184,17 @@ type promptVarsResult struct { StdinBoundToVar bool } -// promptVars builds the template data from --var key=value pairs and a --vars +// ParsePromptVariables builds template data from --var key=value pairs and a --vars // JSON blob; unused stdin is exposed as {{input}}. -func promptVars(opts AIPromptOptions, varsJSON, stdin string, usedStdin bool) (promptVarsResult, error) { +func ParsePromptVariables(opts AIPromptOptions, varsJSON, stdin string, usedStdin bool) (promptVarsResult, error) { data := map[string]any{} if s := strings.TrimSpace(varsJSON); s != "" { if err := json.Unmarshal([]byte(s), &data); err != nil { return promptVarsResult{}, fmt.Errorf("parse --vars JSON: %w", err) } + if data == nil { + return promptVarsResult{}, fmt.Errorf("--vars must be a JSON object, got null") + } } kv, boundStdin, err := parseVars(opts.Var, stdin) if err != nil { diff --git a/pkg/lint/promptfile/run.go b/pkg/lint/promptfile/run.go new file mode 100644 index 00000000..e8fcc9f1 --- /dev/null +++ b/pkg/lint/promptfile/run.go @@ -0,0 +1,129 @@ +package promptfile + +import ( + "context" + "errors" + "fmt" + "os" + "path/filepath" + "slices" + + "github.com/flanksource/captain/pkg/ai/prompt" + "github.com/flanksource/clicky" + commonsContext "github.com/flanksource/commons/context" + "github.com/flanksource/gavel/linters" + "github.com/flanksource/gavel/models" + "github.com/flanksource/gavel/utils" +) + +type Options struct { + WorkDir string + Paths []string + Data map[string]any +} + +func Run(ctx context.Context, options Options) []*linters.LinterResult { + linter := &promptfileLinter{options: options} + result := linters.RunLinterWithTask(ctx, nil, linter, linters.RunOptions{WorkDir: options.WorkDir}) + if result.Violations == nil { + result.Violations = []models.Violation{} + } + return []*linters.LinterResult{result} +} + +type promptfileLinter struct { + options Options + fileCount int +} + +var _ linters.Linter = (*promptfileLinter)(nil) + +func (*promptfileLinter) Name() string { return "promptfile" } +func (*promptfileLinter) DefaultIncludes() []string { return []string{"**/*.prompt"} } +func (*promptfileLinter) DefaultExcludes() []string { return nil } +func (*promptfileLinter) SupportsJSON() bool { return true } +func (*promptfileLinter) JSONArgs() []string { return nil } +func (*promptfileLinter) SupportsFix() bool { return false } +func (*promptfileLinter) FixArgs() []string { return nil } +func (*promptfileLinter) ValidateConfig(*models.LinterConfig) error { return nil } +func (*promptfileLinter) GetRuleCount() int { return 7 } +func (l *promptfileLinter) GetFileCount() int { return l.fileCount } + +func (l *promptfileLinter) Run(ctx commonsContext.Context, _ *clicky.Task) ([]models.Violation, error) { + workDir := l.options.WorkDir + if workDir == "" { + workDir = "." + } + root, err := filepath.Abs(workDir) + if err != nil { + return nil, fmt.Errorf("resolve working directory: %w", err) + } + files, err := discover(root, l.options.Paths) + if err != nil { + return nil, err + } + var violations []models.Violation + var failures []error + for _, path := range files { + if err := ctx.Err(); err != nil { + return violations, errors.Join(append(failures, err)...) + } + template, err := prompt.LoadFile(path) + if err != nil { + failures = append(failures, err) + continue + } + l.fileCount++ + file, err := filepath.Rel(root, path) + if err != nil { + return violations, err + } + for _, diagnostic := range template.Validate(prompt.ValidationOptions{Data: l.options.Data}) { + violation := models.NewViolationBuilder().WithFile(filepath.ToSlash(file)).WithSource(l.Name()). + WithRuleFromLinter(l.Name(), diagnostic.Rule).WithLocation(diagnostic.Line, diagnostic.Column). + WithMessage(diagnostic.Message).Build() + violation.Severity = models.ViolationSeverity(diagnostic.Severity) + violations = append(violations, violation) + } + } + return violations, errors.Join(failures...) +} + +func discover(root string, paths []string) ([]string, error) { + if len(paths) == 0 { + paths = []string{"."} + } + seen := map[string]bool{} + for _, path := range paths { + if !filepath.IsAbs(path) { + path = filepath.Join(root, path) + } + info, err := os.Stat(path) + if err != nil { + return nil, fmt.Errorf("select promptfiles: %w", err) + } + if !info.IsDir() { + if filepath.Ext(path) != ".prompt" { + return nil, fmt.Errorf("expected a .prompt file: %s", path) + } + seen[filepath.Clean(path)] = true + continue + } + matches, err := utils.GlobFilesBounded(path, []string{"**/*.prompt"}) + if err != nil { + return nil, fmt.Errorf("discover promptfiles in %s: %w", path, err) + } + for _, match := range matches { + seen[match] = true + } + } + files := make([]string, 0, len(seen)) + for file := range seen { + files = append(files, file) + } + if len(files) == 0 { + return nil, errors.New("no .prompt files matched the selected paths") + } + slices.Sort(files) + return files, nil +} diff --git a/pkg/lint/promptfile/run_ginkgo_test.go b/pkg/lint/promptfile/run_ginkgo_test.go new file mode 100644 index 00000000..26f7f58b --- /dev/null +++ b/pkg/lint/promptfile/run_ginkgo_test.go @@ -0,0 +1,106 @@ +package promptfile + +import ( + "context" + "os" + "path/filepath" + "testing" + + "github.com/flanksource/gavel/models" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +func TestPromptfile(t *testing.T) { + RegisterFailHandler(Fail) + RunSpecs(t, "Promptfile linter") +} + +var _ = Describe("Promptfile linter", func() { + var directory string + BeforeEach(func() { directory = GinkgoT().TempDir() }) + + write := func(path, content string) { + Expect(os.MkdirAll(filepath.Dir(path), 0o755)).To(Succeed()) + Expect(os.WriteFile(path, []byte(content), 0o600)).To(Succeed()) + } + + It("discovers promptfiles recursively, respecting gitignore and duplicate paths", func() { + Expect(os.Mkdir(filepath.Join(directory, ".git"), 0o755)).To(Succeed()) + write(filepath.Join(directory, ".gitignore"), "ignored/\n") + write(filepath.Join(directory, "a.prompt"), "Review {{missing}}.\n") + write(filepath.Join(directory, "nested", "b.prompt"), "---\nmode: invalid\n---\nbody\n") + write(filepath.Join(directory, "ignored", "bad.prompt"), "{{#if broken}}\n") + write(filepath.Join(directory, "readme.md"), "{{#if broken}}\n") + results := Run(context.Background(), Options{WorkDir: directory, Paths: []string{".", "a.prompt"}}) + Expect(results).To(HaveLen(1)) + Expect(results[0].Linter).To(Equal("promptfile")) + Expect(results[0].Success).To(BeTrue()) + Expect(results[0].FileCount).To(Equal(2)) + Expect(results[0].Violations).To(HaveLen(1)) + Expect(results[0].Violations[0].File).To(Equal("nested/b.prompt")) + Expect(results[0].Test().Sum().Failed).To(Equal(1)) + }) + + It("checks explicit ignored files", func() { + Expect(os.Mkdir(filepath.Join(directory, ".git"), 0o755)).To(Succeed()) + write(filepath.Join(directory, ".gitignore"), "ignored.prompt\n") + write(filepath.Join(directory, "ignored.prompt"), "{{#if broken}}\n") + results := Run(context.Background(), Options{WorkDir: directory, Paths: []string{"ignored.prompt"}}) + Expect(results).To(HaveLen(1)) + Expect(results[0].FileCount).To(Equal(1)) + Expect(results[0].Test().Sum().Failed).To(Equal(1)) + }) + + It("defaults to the working directory and orders findings by path", func() { + write(filepath.Join(directory, "z.prompt"), "{{#if broken}}\n") + write(filepath.Join(directory, "a.prompt"), "{{#if broken}}\n") + results := Run(context.Background(), Options{WorkDir: directory}) + Expect(results).To(HaveLen(1)) + Expect(results[0].Violations).To(HaveLen(2)) + Expect(results[0].Violations[0].File).To(Equal("a.prompt")) + Expect(results[0].Violations[1].File).To(Equal("z.prompt")) + }) + + DescribeTable("reports selection errors as failed linter results", + func(paths []string, message string) { + results := Run(context.Background(), Options{WorkDir: directory, Paths: paths}) + Expect(results).To(HaveLen(1)) + Expect(results[0].Success).To(BeFalse()) + Expect(results[0].Error).To(ContainSubstring(message)) + Expect(results[0].Test().Sum().Failed).To(Equal(1)) + }, + Entry("empty directory", nil, "no .prompt files"), + Entry("missing path", []string{"missing.prompt"}, "missing.prompt"), + ) + + It("fails on explicit non-prompt files", func() { + write(filepath.Join(directory, "notes.md"), "Review.\n") + results := Run(context.Background(), Options{WorkDir: directory, Paths: []string{"notes.md"}}) + Expect(results).To(HaveLen(1)) + Expect(results[0].Success).To(BeFalse()) + Expect(results[0].Error).To(ContainSubstring(".prompt")) + }) + + It("keeps incomplete-input warnings non-failing and accepts sample inputs", func() { + write(filepath.Join(directory, "review.prompt"), "---\nbudget:\n maxTokens: {{limit}}\n---\nReview {{missing}}\n") + results := Run(context.Background(), Options{WorkDir: directory}) + Expect(results).To(HaveLen(1)) + Expect(results[0].Violations).To(HaveLen(1)) + Expect(results[0].Violations[0].Severity).To(Equal(models.SeverityWarning)) + Expect(results[0].Test().Sum().Failed).To(BeZero()) + results = Run(context.Background(), Options{WorkDir: directory, Data: map[string]any{"limit": 100}}) + Expect(results[0].Violations).To(BeEmpty()) + Expect(results[0].Success).To(BeTrue()) + }) + + It("honors cancellation", func() { + write(filepath.Join(directory, "review.prompt"), "Review.\n") + ctx, cancel := context.WithCancel(context.Background()) + cancel() + results := Run(ctx, Options{WorkDir: directory}) + Expect(results).To(HaveLen(1)) + Expect(results[0].Success).To(BeFalse()) + Expect(results[0].Error).To(ContainSubstring("context canceled")) + }) +}) From f9e7a7a79b6404e4d1239abef1ee380616427070 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Thu, 22 Oct 2026 18:49:36 +0300 Subject: [PATCH 05/77] feat(brand): add Captain Formation logo kit with usage guidelines Add the Captain Formation brand kit: horizontal, stacked, symbol, and wordmark masters, dark and one-colour variants, a small-size drawing, and web and social icons. Lettering is outlined vector geometry, so no font installation is required. Web handover files are provided for manual integration; application code is unchanged. PNG exports follow the existing *.png ignore rule. Trademark clearance and print approval remain outstanding. --- assets/brand/captain-formation/GUIDELINES.md | 44 ++++++++++++++++ assets/brand/captain-formation/README.md | 49 ++++++++++++++++++ .../digital/captain-horizontal-black.svg | 13 +++++ .../captain-horizontal-mono-c45125.svg | 13 +++++ .../digital/captain-horizontal-white.svg | 13 +++++ .../digital/captain-stacked-black.svg | 13 +++++ .../digital/captain-stacked-mono-c45125.svg | 13 +++++ .../digital/captain-stacked-white.svg | 13 +++++ .../digital/captain-symbol-black.svg | 4 ++ .../digital/captain-symbol-mono-18252b.svg | 4 ++ .../digital/captain-symbol-mono-c45125.svg | 4 ++ .../digital/captain-symbol-mono-f2a477.svg | 4 ++ .../captain-symbol-small-mono-f2a477.svg | 4 ++ .../digital/captain-symbol-small-white.svg | 4 ++ .../digital/captain-symbol-white.svg | 4 ++ .../digital/captain-wordmark-black.svg | 12 +++++ .../digital/captain-wordmark-mono-c45125.svg | 12 +++++ .../digital/captain-wordmark-white.svg | 12 +++++ .../social/captain-avatar.svg | 5 ++ .../source/captain-horizontal-dark.svg | 13 +++++ .../source/captain-horizontal.svg | 13 +++++ .../source/captain-stacked-dark.svg | 13 +++++ .../source/captain-stacked.svg | 13 +++++ .../source/captain-symbol-reverse.svg | 4 ++ .../source/captain-symbol-small.svg | 4 ++ .../source/captain-symbol.svg | 4 ++ .../source/captain-wordmark.svg | 12 +++++ .../web/captain-app-icon.svg | 4 ++ .../captain-formation/web/captain-favicon.svg | 4 ++ .../brand/captain-formation/web/favicon.ico | Bin 0 -> 1305 bytes .../brand/captain-formation/web/favicon.svg | 5 ++ .../captain-formation/web/head-snippet.html | 5 ++ .../captain-formation/web/site.webmanifest | 25 +++++++++ 33 files changed, 359 insertions(+) create mode 100644 assets/brand/captain-formation/GUIDELINES.md create mode 100644 assets/brand/captain-formation/README.md create mode 100644 assets/brand/captain-formation/digital/captain-horizontal-black.svg create mode 100644 assets/brand/captain-formation/digital/captain-horizontal-mono-c45125.svg create mode 100644 assets/brand/captain-formation/digital/captain-horizontal-white.svg create mode 100644 assets/brand/captain-formation/digital/captain-stacked-black.svg create mode 100644 assets/brand/captain-formation/digital/captain-stacked-mono-c45125.svg create mode 100644 assets/brand/captain-formation/digital/captain-stacked-white.svg create mode 100644 assets/brand/captain-formation/digital/captain-symbol-black.svg create mode 100644 assets/brand/captain-formation/digital/captain-symbol-mono-18252b.svg create mode 100644 assets/brand/captain-formation/digital/captain-symbol-mono-c45125.svg create mode 100644 assets/brand/captain-formation/digital/captain-symbol-mono-f2a477.svg create mode 100644 assets/brand/captain-formation/digital/captain-symbol-small-mono-f2a477.svg create mode 100644 assets/brand/captain-formation/digital/captain-symbol-small-white.svg create mode 100644 assets/brand/captain-formation/digital/captain-symbol-white.svg create mode 100644 assets/brand/captain-formation/digital/captain-wordmark-black.svg create mode 100644 assets/brand/captain-formation/digital/captain-wordmark-mono-c45125.svg create mode 100644 assets/brand/captain-formation/digital/captain-wordmark-white.svg create mode 100644 assets/brand/captain-formation/social/captain-avatar.svg create mode 100644 assets/brand/captain-formation/source/captain-horizontal-dark.svg create mode 100644 assets/brand/captain-formation/source/captain-horizontal.svg create mode 100644 assets/brand/captain-formation/source/captain-stacked-dark.svg create mode 100644 assets/brand/captain-formation/source/captain-stacked.svg create mode 100644 assets/brand/captain-formation/source/captain-symbol-reverse.svg create mode 100644 assets/brand/captain-formation/source/captain-symbol-small.svg create mode 100644 assets/brand/captain-formation/source/captain-symbol.svg create mode 100644 assets/brand/captain-formation/source/captain-wordmark.svg create mode 100644 assets/brand/captain-formation/web/captain-app-icon.svg create mode 100644 assets/brand/captain-formation/web/captain-favicon.svg create mode 100644 assets/brand/captain-formation/web/favicon.ico create mode 100644 assets/brand/captain-formation/web/favicon.svg create mode 100644 assets/brand/captain-formation/web/head-snippet.html create mode 100644 assets/brand/captain-formation/web/site.webmanifest diff --git a/assets/brand/captain-formation/GUIDELINES.md b/assets/brand/captain-formation/GUIDELINES.md new file mode 100644 index 00000000..505c4be2 --- /dev/null +++ b/assets/brand/captain-formation/GUIDELINES.md @@ -0,0 +1,44 @@ +# Captain / Formation + +Independent agents. One heading. Three separate bands form one directional silhouette. Use the supplied artwork; the lowercase wordmark is original outlined lettering. + +## Choose the artwork + +| Use | File | +| --- | --- | +| Light background | `source/captain-horizontal.svg` | +| Dark background | `source/captain-horizontal-dark.svg` | +| Centred placement | `source/captain-stacked.svg` or `source/captain-stacked-dark.svg` | +| Symbol, 48 px and larger | `source/captain-symbol.svg` | +| Symbol, 16–47 px | `source/captain-symbol-small.svg`; white/warm versions in `digital/` | +| Browser tab | Adaptive `web/favicon.svg`; PNG and ICO alternatives are included | +| App / social tile | `web/captain-app-icon.svg` or `social/captain-avatar.svg` | +| One colour | Black, white, and orange SVGs in `digital/` | + +## Space and size + +Keep clear space equal to the central band's thickness: **40 units on the 256-unit symbol grid**, measured outside the visible artwork. Scale that distance with the logo. Built-in canvas padding counts towards this space; add the balance in the surrounding layout. Use the existing proportions and spacing within each lockup. + +Minimum screen sizes: **horizontal 160 px wide; stacked 160 px wide; wordmark 128 px wide; small symbol 16 px square; app tile 32 px square**. Use the dedicated small drawing below 48 px. Print starting points are 35 mm horizontal, 30 mm stacked, and 6 mm symbol; inspect a physical proof before production. + +## Palette + +| Colour | HEX | RGB | Approximate CMYK % | Role | +| --- | --- | --- | --- | --- | +| Signal orange | `#C45125` | 196, 81, 37 | 0, 59, 81, 23 | Primary symbol; solid logo tile | +| Graphite | `#18252B` | 24, 37, 43 | 44, 14, 0, 83 | Wordmark; dark background | +| Warm signal | `#F2A477` | 242, 164, 119 | 0, 32, 51, 5 | Symbol on graphite | +| Paper | `#F5F4F0` | 245, 244, 240 | 0, 0, 2, 4 | Canvas | +| White | `#FFFFFF` | 255, 255, 255 | 0, 0, 0, 0 | Reversed artwork | + +Approved pairs: orange/graphite on white or Paper; warm signal/white on Graphite; white on Signal orange; black on white. Keep warm signal for dark surfaces. On photography, use a solid approved tile behind the mark. + +CMYK numbers are mathematical starting points, not profile-specific press values. No Pantone match or physical proof has been approved; have the printer match a physical spot-ink guide before a print run. + +## Typography and handling + +The logo requires no installed font. Supporting text uses the platform's system sans-serif stack; monospace is reserved for commands and code. No font files are distributed. + +Preserve the mark's orientation, silhouette, three separate bands, and lockup proportions. Use the supplied reverse and small-size drawings. Keep artwork flat and leave clear space free of text or decoration. All SVG masters remain editable vector outlines. + +Masters and handover notes live beside this guide. Public trademark clearance remains outside the supplied artwork checks. diff --git a/assets/brand/captain-formation/README.md b/assets/brand/captain-formation/README.md new file mode 100644 index 00000000..1e11362f --- /dev/null +++ b/assets/brand/captain-formation/README.md @@ -0,0 +1,49 @@ +# Captain / Formation logo kit + +Formation is the direction selected by Moshe. This kit develops it in Signal orange and Graphite, with original outlined lettering and dedicated dark, reversed, and small-size artwork. It contains design assets only; application integration is separate. + +Start with [the identity overview](presentation/overview.png), [the usage guide](GUIDELINES.md), and [the presentation board](presentation/board.html). The board shows six illustrative contexts: README, app icon, website header, terminal, sticker, and social profile. The terminal example uses existing Captain commands; it is not a captured CLI session. + +## Files + +| Folder | Contents | +| --- | --- | +| `source/` | Colour horizontal/stacked/symbol/wordmark masters, dark lockups, reverse symbol, small drawing | +| `digital/` | Black, white, orange, Graphite, and warm-signal SVGs; transparent PNG exports | +| `web/` | Adaptive SVG favicon, ICO with 16/32/48 px frames, matching PNGs, app tile, Apple/PWA icons, manifest, head snippet | +| `social/` | Graphite avatar with a circle-safe symbol, SVG and 1024 px PNG | +| `presentation/` | Overview SVG/PNG, HTML board and spec, browser mockup capture, and export QA page/screenshots | + +The primary source files are `source/captain-horizontal.svg` for light backgrounds and `source/captain-horizontal-dark.svg` for dark backgrounds. Use `source/captain-symbol-small.svg` below 48 px. White and warm small versions are in `digital/`. The ordinary white symbol and white lockups have slightly lighter symbol geometry to balance apparent weight on dark backgrounds. + +The small drawing opens the band's gaps from 20 to 24 units and makes the central band 48 units high. Favicons use that drawing. App artwork occupies 66% of its tile; the maskable icon reduces it to 50% so the mark remains inside the platform's safe circle. PWA and Apple icons have full-bleed backgrounds; the decorative app tile retains rounded corners. + +## Web handover + +Copy the files in `web/` to the host application's public root and include the markup in `web/head-snippet.html`. The manifest's image paths are relative to the manifest; the supplied head snippet assumes a public-root installation. For a different prefix, update the snippet's URLs to match. Review the host's existing manifest before replacing it. + +The SVG favicon changes from Signal orange to Warm signal under `prefers-color-scheme: dark`. Its default fill remains explicit for SVG consumers that do not process the style block. PNG and ICO alternatives use the primary orange and do not adapt. + +To inspect the local presentation and export checks from the repository root: + +```bash +python3 -m http.server 19372 --bind 127.0.0.1 --directory assets/brand/captain-formation +``` + +Open `http://127.0.0.1:19372/presentation/board.html` for the deck or `http://127.0.0.1:19372/presentation/qa.html` for the exact-size checks. Stop the server when finished. The overview SVG and HTML board contain their artwork internally and remain portable when shared. + +## Verification + +- SVG structure and geometry checked across every master and exported SVG. The stacked lockups retain an informational complexity note because their seven outlined letters contribute most of the points. The favicon's conditional style and the app tile also have expected informational notes. +- Light and dark logo/background pairs passed the audit's 3:1 logo-contrast threshold. Colour carries no meaning that is lost in the one-colour versions. +- Actual browser checks covered 16, 24, 32, and 48 px symbols; PNG favicons; minimum lockup sizes; the adaptive favicon in light and dark modes; and the QA page at desktop and 390 px widths. +- PNG dimensions checked: favicons 16/32/48, Apple 180, PWA 192/512, maskable 512, app tile 512/1024, horizontal colour 1776×512, stacked colour 1280×1024, avatar 1024×1024. The ICO contains three sizes. Transparent logo exports retain alpha; full-bleed install icons are opaque. +- The six mockups were inspected in Chrome through agent-browser. Browser checks succeeded in this pass; the earlier concept-round timeouts were not reproduced. + +Run the artwork audit from the repository root: + +```bash +python3 /Users/moshe/.agents/skills/logo-design/scripts/svg_audit.py assets/brand/captain-formation/source/*.svg assets/brand/captain-formation/digital/*.svg assets/brand/captain-formation/web/*.svg assets/brand/captain-formation/social/*.svg +``` + +The palette, clear space, and size rules are in [GUIDELINES.md](GUIDELINES.md). All lettering is filled vector geometry with no installed-font dependency. No physical print proof, Pantone assignment, or professional trademark clearance is included. Application build/lint gates are outside this asset-only change; no application source was edited. PNG exports follow the repository's existing `*.png` ignore rule; the downloadable kit archive includes them. diff --git a/assets/brand/captain-formation/digital/captain-horizontal-black.svg b/assets/brand/captain-formation/digital/captain-horizontal-black.svg new file mode 100644 index 00000000..9a4ca67c --- /dev/null +++ b/assets/brand/captain-formation/digital/captain-horizontal-black.svg @@ -0,0 +1,13 @@ + + Captain Formation horizontal logo + + + + + + + + + + + diff --git a/assets/brand/captain-formation/digital/captain-horizontal-mono-c45125.svg b/assets/brand/captain-formation/digital/captain-horizontal-mono-c45125.svg new file mode 100644 index 00000000..e31ecd2f --- /dev/null +++ b/assets/brand/captain-formation/digital/captain-horizontal-mono-c45125.svg @@ -0,0 +1,13 @@ + + Captain Formation horizontal logo + + + + + + + + + + + diff --git a/assets/brand/captain-formation/digital/captain-horizontal-white.svg b/assets/brand/captain-formation/digital/captain-horizontal-white.svg new file mode 100644 index 00000000..53daac54 --- /dev/null +++ b/assets/brand/captain-formation/digital/captain-horizontal-white.svg @@ -0,0 +1,13 @@ + + Captain Formation horizontal logo for dark backgrounds + + + + + + + + + + + diff --git a/assets/brand/captain-formation/digital/captain-stacked-black.svg b/assets/brand/captain-formation/digital/captain-stacked-black.svg new file mode 100644 index 00000000..579be280 --- /dev/null +++ b/assets/brand/captain-formation/digital/captain-stacked-black.svg @@ -0,0 +1,13 @@ + + Captain Formation stacked logo + + + + + + + + + + + diff --git a/assets/brand/captain-formation/digital/captain-stacked-mono-c45125.svg b/assets/brand/captain-formation/digital/captain-stacked-mono-c45125.svg new file mode 100644 index 00000000..4224a21d --- /dev/null +++ b/assets/brand/captain-formation/digital/captain-stacked-mono-c45125.svg @@ -0,0 +1,13 @@ + + Captain Formation stacked logo + + + + + + + + + + + diff --git a/assets/brand/captain-formation/digital/captain-stacked-white.svg b/assets/brand/captain-formation/digital/captain-stacked-white.svg new file mode 100644 index 00000000..88de8439 --- /dev/null +++ b/assets/brand/captain-formation/digital/captain-stacked-white.svg @@ -0,0 +1,13 @@ + + Captain Formation stacked logo for dark backgrounds + + + + + + + + + + + diff --git a/assets/brand/captain-formation/digital/captain-symbol-black.svg b/assets/brand/captain-formation/digital/captain-symbol-black.svg new file mode 100644 index 00000000..f4a1a952 --- /dev/null +++ b/assets/brand/captain-formation/digital/captain-symbol-black.svg @@ -0,0 +1,4 @@ + + Captain Formation symbol + + diff --git a/assets/brand/captain-formation/digital/captain-symbol-mono-18252b.svg b/assets/brand/captain-formation/digital/captain-symbol-mono-18252b.svg new file mode 100644 index 00000000..c0439fa2 --- /dev/null +++ b/assets/brand/captain-formation/digital/captain-symbol-mono-18252b.svg @@ -0,0 +1,4 @@ + + Captain Formation symbol + + diff --git a/assets/brand/captain-formation/digital/captain-symbol-mono-c45125.svg b/assets/brand/captain-formation/digital/captain-symbol-mono-c45125.svg new file mode 100644 index 00000000..8bb23686 --- /dev/null +++ b/assets/brand/captain-formation/digital/captain-symbol-mono-c45125.svg @@ -0,0 +1,4 @@ + + Captain Formation symbol + + diff --git a/assets/brand/captain-formation/digital/captain-symbol-mono-f2a477.svg b/assets/brand/captain-formation/digital/captain-symbol-mono-f2a477.svg new file mode 100644 index 00000000..6e9db017 --- /dev/null +++ b/assets/brand/captain-formation/digital/captain-symbol-mono-f2a477.svg @@ -0,0 +1,4 @@ + + Captain Formation symbol in reverse + + diff --git a/assets/brand/captain-formation/digital/captain-symbol-small-mono-f2a477.svg b/assets/brand/captain-formation/digital/captain-symbol-small-mono-f2a477.svg new file mode 100644 index 00000000..f190ecba --- /dev/null +++ b/assets/brand/captain-formation/digital/captain-symbol-small-mono-f2a477.svg @@ -0,0 +1,4 @@ + + Captain Formation symbol for small sizes + + diff --git a/assets/brand/captain-formation/digital/captain-symbol-small-white.svg b/assets/brand/captain-formation/digital/captain-symbol-small-white.svg new file mode 100644 index 00000000..c00118d7 --- /dev/null +++ b/assets/brand/captain-formation/digital/captain-symbol-small-white.svg @@ -0,0 +1,4 @@ + + Captain Formation symbol for small sizes + + diff --git a/assets/brand/captain-formation/digital/captain-symbol-white.svg b/assets/brand/captain-formation/digital/captain-symbol-white.svg new file mode 100644 index 00000000..3da9146e --- /dev/null +++ b/assets/brand/captain-formation/digital/captain-symbol-white.svg @@ -0,0 +1,4 @@ + + Captain Formation symbol in reverse + + diff --git a/assets/brand/captain-formation/digital/captain-wordmark-black.svg b/assets/brand/captain-formation/digital/captain-wordmark-black.svg new file mode 100644 index 00000000..0e00f2b7 --- /dev/null +++ b/assets/brand/captain-formation/digital/captain-wordmark-black.svg @@ -0,0 +1,12 @@ + + Captain custom wordmark + + + + + + + + + + diff --git a/assets/brand/captain-formation/digital/captain-wordmark-mono-c45125.svg b/assets/brand/captain-formation/digital/captain-wordmark-mono-c45125.svg new file mode 100644 index 00000000..987cff87 --- /dev/null +++ b/assets/brand/captain-formation/digital/captain-wordmark-mono-c45125.svg @@ -0,0 +1,12 @@ + + Captain custom wordmark + + + + + + + + + + diff --git a/assets/brand/captain-formation/digital/captain-wordmark-white.svg b/assets/brand/captain-formation/digital/captain-wordmark-white.svg new file mode 100644 index 00000000..79fa3af7 --- /dev/null +++ b/assets/brand/captain-formation/digital/captain-wordmark-white.svg @@ -0,0 +1,12 @@ + + Captain custom wordmark + + + + + + + + + + diff --git a/assets/brand/captain-formation/social/captain-avatar.svg b/assets/brand/captain-formation/social/captain-avatar.svg new file mode 100644 index 00000000..fd372ce2 --- /dev/null +++ b/assets/brand/captain-formation/social/captain-avatar.svg @@ -0,0 +1,5 @@ + + Captain Formation avatar + + + diff --git a/assets/brand/captain-formation/source/captain-horizontal-dark.svg b/assets/brand/captain-formation/source/captain-horizontal-dark.svg new file mode 100644 index 00000000..dca3697a --- /dev/null +++ b/assets/brand/captain-formation/source/captain-horizontal-dark.svg @@ -0,0 +1,13 @@ + + Captain Formation horizontal logo for dark backgrounds + + + + + + + + + + + diff --git a/assets/brand/captain-formation/source/captain-horizontal.svg b/assets/brand/captain-formation/source/captain-horizontal.svg new file mode 100644 index 00000000..157db7f0 --- /dev/null +++ b/assets/brand/captain-formation/source/captain-horizontal.svg @@ -0,0 +1,13 @@ + + Captain Formation horizontal logo + + + + + + + + + + + diff --git a/assets/brand/captain-formation/source/captain-stacked-dark.svg b/assets/brand/captain-formation/source/captain-stacked-dark.svg new file mode 100644 index 00000000..8f2eb796 --- /dev/null +++ b/assets/brand/captain-formation/source/captain-stacked-dark.svg @@ -0,0 +1,13 @@ + + Captain Formation stacked logo for dark backgrounds + + + + + + + + + + + diff --git a/assets/brand/captain-formation/source/captain-stacked.svg b/assets/brand/captain-formation/source/captain-stacked.svg new file mode 100644 index 00000000..85792f05 --- /dev/null +++ b/assets/brand/captain-formation/source/captain-stacked.svg @@ -0,0 +1,13 @@ + + Captain Formation stacked logo + + + + + + + + + + + diff --git a/assets/brand/captain-formation/source/captain-symbol-reverse.svg b/assets/brand/captain-formation/source/captain-symbol-reverse.svg new file mode 100644 index 00000000..bc1c7f32 --- /dev/null +++ b/assets/brand/captain-formation/source/captain-symbol-reverse.svg @@ -0,0 +1,4 @@ + + Captain Formation symbol in reverse + + diff --git a/assets/brand/captain-formation/source/captain-symbol-small.svg b/assets/brand/captain-formation/source/captain-symbol-small.svg new file mode 100644 index 00000000..32088c5e --- /dev/null +++ b/assets/brand/captain-formation/source/captain-symbol-small.svg @@ -0,0 +1,4 @@ + + Captain Formation symbol for small sizes + + diff --git a/assets/brand/captain-formation/source/captain-symbol.svg b/assets/brand/captain-formation/source/captain-symbol.svg new file mode 100644 index 00000000..2822a7bb --- /dev/null +++ b/assets/brand/captain-formation/source/captain-symbol.svg @@ -0,0 +1,4 @@ + + Captain Formation symbol + + diff --git a/assets/brand/captain-formation/source/captain-wordmark.svg b/assets/brand/captain-formation/source/captain-wordmark.svg new file mode 100644 index 00000000..dea6b1de --- /dev/null +++ b/assets/brand/captain-formation/source/captain-wordmark.svg @@ -0,0 +1,12 @@ + + Captain custom wordmark + + + + + + + + + + diff --git a/assets/brand/captain-formation/web/captain-app-icon.svg b/assets/brand/captain-formation/web/captain-app-icon.svg new file mode 100644 index 00000000..5fbc85f8 --- /dev/null +++ b/assets/brand/captain-formation/web/captain-app-icon.svg @@ -0,0 +1,4 @@ +Captain + Captain Formation symbol for small sizes + + \ No newline at end of file diff --git a/assets/brand/captain-formation/web/captain-favicon.svg b/assets/brand/captain-formation/web/captain-favicon.svg new file mode 100644 index 00000000..612853d7 --- /dev/null +++ b/assets/brand/captain-formation/web/captain-favicon.svg @@ -0,0 +1,4 @@ +Captain + Captain Formation symbol for small sizes + + \ No newline at end of file diff --git a/assets/brand/captain-formation/web/favicon.ico b/assets/brand/captain-formation/web/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..2b4a60958fddb610aa2e90a2f2c7137fc68c8158 GIT binary patch literal 1305 zcmZQzU}Rus5D;Jh(h3X#j0_BB3=9kk3K0GTAioWW4GbWBW+ny(F=hsa&Hz7mUM?vv zpi*8>50@Yy4K#s4fP)Q4%76Z!2&CAOyxm3pQrhItp!M(L&*rF)kKPr3ic{m?{&elxhjaEa@inV? zW$&;$(I>svCgX$njGy7?gb`pvSFOSqO7ab&qZ^=)15lKIZ?s?+Az|AZMjzA&Wycav6f zcm0(6QO4z2+`cvXAx)gebaR|zY$9HUH--9%GS}EUI?mas-c-_X&i`e`+^u0b-)!)|h{4m<&t;ucLKBwoQ~*jVfWx!6s_F}ngBhN#pzw@neS6)|`>=xq z+k@|?Rqw{!iSaHu`6MGCXTfTZ1wR?TvHxU$Wq%^5P;~mOhRMMWx-+zPOlydq{H$20 zX^U@B(e$P7E6U~HJ1abKikNIsV3oOTk48st>F-d%Wr8~&-VUF;c}r&UEBQFX0%ixM zgYv6mDxR0G?=*1`PttZ^UnI0ZDv*1DP@wbzu8SNCm@Y~%F!cYssJYl;!c14k`RUs? ztFOEn8`83DU+u{S*|MoTDwgTY`8NLb*L@7WIlOqqAaG%8f~`yA`L%qOT2Cq!^0~Ka#{Oz8hml%*>k>a4Zf+r4bd zKTEUO=lpA`IX-ka1c?hdE((v!{KBHP&sOCE$E59w2h-lC{4tu&v_fM&Z$M}q_kvA( zgcj_o(ROhE>DF-W{%3iEEoa+G{@zsq1~I<)0OkM&18{tVGyQDG8Xr4A@sZK^cGg}$ zCPxvs^9&bTMBiMUbmUNrcz}zP5VxmB4O{hB&NmCcD(WZ*`g)is9=tT|*asFdlUIvA z8Hb4}ZKz*tJo$}gxq11%&1Zey$u_d@eLQz+4sR>oSfU*i^E5r~uDa=P+( zVVmv)g;P%41-;VA|IgLb5Q@|{`IWx;ys*`w7DolY-B)9B zzwI<-GKfE<#rQ)vaW2E3DI01lRyZePGY!A;Q-1yedYJ2%R_zOAJh$_@0TyGr|Yp)RMl^^67T!GSZc3kO|` ziYab07wXb_b@s#dwXSm?IyzRzrdM=WJh&h$r_?jUhl5|Sy=GZUyFhZ-{2a#(KzkLdN>eGJ0S_1xAZ$X`cJ0sx798ZiI> literal 0 HcmV?d00001 diff --git a/assets/brand/captain-formation/web/favicon.svg b/assets/brand/captain-formation/web/favicon.svg new file mode 100644 index 00000000..7b05d5ce --- /dev/null +++ b/assets/brand/captain-formation/web/favicon.svg @@ -0,0 +1,5 @@ + + Captain + + + diff --git a/assets/brand/captain-formation/web/head-snippet.html b/assets/brand/captain-formation/web/head-snippet.html new file mode 100644 index 00000000..2bebe2b5 --- /dev/null +++ b/assets/brand/captain-formation/web/head-snippet.html @@ -0,0 +1,5 @@ + + + + + diff --git a/assets/brand/captain-formation/web/site.webmanifest b/assets/brand/captain-formation/web/site.webmanifest new file mode 100644 index 00000000..24af6426 --- /dev/null +++ b/assets/brand/captain-formation/web/site.webmanifest @@ -0,0 +1,25 @@ +{ + "name": "Captain", + "short_name": "Captain", + "icons": [ + { + "src": "icon-192.png", + "sizes": "192x192", + "type": "image/png" + }, + { + "src": "icon-512.png", + "sizes": "512x512", + "type": "image/png" + }, + { + "src": "maskable-512.png", + "sizes": "512x512", + "type": "image/png", + "purpose": "maskable" + } + ], + "theme_color": "#C45125", + "background_color": "#C45125", + "display": "standalone" +} From d6986abb2347f9287a5112c1dac7e8ec11f650c5 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Thu, 22 Oct 2026 18:51:44 +0300 Subject: [PATCH 06/77] feat(prompts): add ordered presets, Lint preset and built-in document review prompts Presets gain an integer order (default 0) that sorts layers ahead of scope precedence, so the Lint preset can apply after prompt and request layers. The Lint preset replaces output schemas with a violations contract that gavel lint prompt renders as lint results. Five read-only document review prompts ship in pkg/ai/prompt/builtin, and local prompts with the same name shadow them. Adds permissions explain and permissions convert commands. JSON/YAML null on schema fields now clears them explicitly. With saved defaults, a missing token budget stays unset so the runtime applies its own default. --- cmd/captain/main.go | 4 ++ docs/src/components/RuntimeSpecDemo.tsx | 3 +- docs/src/pages/prompts/format.mdx | 38 ++++++++++++++ docs/src/pages/prompts/index.mdx | 2 +- docs/src/pages/prompts/sources-api.mdx | 10 ++-- pkg/api/preset_order_ginkgo_test.go | 37 +++++++++++++ pkg/api/prompt_unmarshal.go | 18 +++++-- pkg/api/prompt_yaml_schema_ginkgo_test.go | 25 +++++++++ pkg/api/runtime_profiles.go | 3 +- pkg/cli/runtime_entity_ginkgo_test.go | 2 +- pkg/cli/webapp/src/runtimeProfilesApi.test.ts | 9 ++++ pkg/cli/webapp/src/runtimeProfilesApi.ts | 3 +- pkg/runtimeprofiles/README.md | 20 +++++-- pkg/runtimeprofiles/builtin/presets/lint.yaml | 52 +++++++++++++++++++ pkg/runtimeprofiles/layers_ginkgo_test.go | 10 ++++ pkg/runtimeprofiles/types.go | 8 +-- 16 files changed, 224 insertions(+), 20 deletions(-) create mode 100644 pkg/api/preset_order_ginkgo_test.go create mode 100644 pkg/api/prompt_yaml_schema_ginkgo_test.go create mode 100644 pkg/runtimeprofiles/builtin/presets/lint.yaml diff --git a/cmd/captain/main.go b/cmd/captain/main.go index c2c19e2a..1e07b344 100644 --- a/cmd/captain/main.go +++ b/cmd/captain/main.go @@ -160,6 +160,10 @@ func newRootCommand() *cobra.Command { rootCmd.AddCommand(permissionsCmd) clicky.AddNamedCommand("matrix", permissionsCmd, cli.PermissionsMatrixOptions{}, cli.RunPermissionsMatrix).Short = "Print the declared permission capability matrix (settings × runtimes)" + clicky.AddNamedCommandWithContext("explain", permissionsCmd, cli.PermissionsExplainOptions{}, cli.RunPermissionsExplain).Short = + "Show what a prompt's permissions compile to on each runtime, and the portable form" + clicky.AddNamedCommand("convert", permissionsCmd, cli.PermissionsConvertOptions{}, cli.RunPermissionsConvert).Short = + "Rewrite a prompt or preset's permissions as permissions.access when the conversion is exact or tighter" sandboxCmd := &cobra.Command{ Use: "sandbox", diff --git a/docs/src/components/RuntimeSpecDemo.tsx b/docs/src/components/RuntimeSpecDemo.tsx index f9fcb544..4cef37e6 100644 --- a/docs/src/components/RuntimeSpecDemo.tsx +++ b/docs/src/components/RuntimeSpecDemo.tsx @@ -1,5 +1,5 @@ import { useState } from "react"; -import { SpecRuntimeEditor, type AISpecRuntimeValue } from "@flanksource/clicky-ui/ai"; +import { RuntimeBar, runtimeSpecFields, SPEC_RUNTIME_FAMILIES, SpecRuntimeEditor, type AISpecRuntimeValue } from "@flanksource/clicky-ui/ai"; import type { ToolMeta } from "@flanksource/clicky-ui/ai"; import { ClickyProviders } from "./ClickyProviders"; @@ -87,6 +87,7 @@ export default function RuntimeSpecDemo() { value={value} onChange={setValue} tools={tools} + beforeSections={} title="Prompt runtime" eyebrow="docs example" /> diff --git a/docs/src/pages/prompts/format.mdx b/docs/src/pages/prompts/format.mdx index 649f02c7..ffdcd441 100644 --- a/docs/src/pages/prompts/format.mdx +++ b/docs/src/pages/prompts/format.mdx @@ -220,3 +220,41 @@ File arguments are checked directly, including explicitly named ignored files. D Missing body variables are allowed because lint does not render the body. Frontmatter variables need values to validate the declarations they generate: without complete sample inputs, lint checks template syntax and emits a `promptfile/variables` warning listing unresolved inputs and the deferred declaration checks. Supply repeated `--var key=value` flags or a `--vars` JSON object to enable those checks. Schema compilation uses bundled declarations and does not fetch external references. Results use Gavel's standard linter-result array, including stable rule IDs, severities, file counts, and source positions where available. Warning-only results exit successfully; invalid content or execution failures exit nonzero. JSON output retains diagnostics on failure. The command performs validation only and does not modify promptfiles. + +## Review documents with Gavel + +`gavel lint prompt` runs a prompt with the `lint` preset, which replaces the prompt's output schema with Gavel's violation contract, so any prompt that asks for located findings works as a linter. Captain ships five built-in document review prompts, resolved by name from any directory. They run as read-only agents: they read the listed files themselves, search the working tree to check concrete references, and report each finding with its file, line, quoted text, severity and a stable `family/name` rule id. Errors fail the lint; warnings and info do not. + + + + + + + + + + + + +
PromptReaderRule families
spec-internal-highTeam deciding what to build: PRDs, RFCs, architecture overviews, plansreq/ doc/ hl/ int/
spec-internal-lowImplementers: detailed, schema and algorithm designsreq/ doc/ ll/ int/
spec-public-highCustomers evaluating: product specs, solution overviews, whitepapersreq/ doc/ hl/ pub/
spec-public-lowExternal integrators: API references, protocol and format specsreq/ doc/ ll/ pub/
proposal-reviewEvaluators: RFP responses, proposals, statements of workreq/ doc/ prop/
+ +`req/` checks requirement quality (verifiable, unambiguous, singular, with units, consistent). `doc/` catches defects common in generated documents: unsourced numbers, cross-section inconsistencies, placeholders, boilerplate, and planned behavior described as existing. `hl/` and `ll/` hold each level to its job, so a PRD is not asked for field types and an API reference is not asked for market rationale. `int/` verifies references against the repository; `pub/` catches internal leaks, undefined terms and missing versioning. `prop/` traces every mandatory RFP requirement to the response when `rfp` is supplied. + +To customize a built-in prompt, copy it from `pkg/ai/prompt/builtin/` into `~/.config/captain/prompts/`, or into a repository's `.captain/prompts/`, under the same name. The local copy shadows the built-in. + + diff --git a/docs/src/pages/prompts/index.mdx b/docs/src/pages/prompts/index.mdx index d0874922..fef6071c 100644 --- a/docs/src/pages/prompts/index.mdx +++ b/docs/src/pages/prompts/index.mdx @@ -19,7 +19,7 @@ Captain prompts are `.prompt` templates rendered through Google dotprompt and fo

Source

-

A prompt can come from a positional file, `--prompt`, stdin (piped, or named with `-`), embedded examples, configured prompt dirs, or the implicit `.captain/prompts` directory. `-p`, `--system`, `--append-system` and `--vars` also accept `@file` or `@url`.

+

A prompt can come from a positional file, `--prompt`, stdin (piped, or named with `-`), embedded examples, built-in prompts, configured prompt dirs, the implicit `.captain/prompts` directory, or the user's `~/.config/captain/prompts` directory. `-p`, `--system`, `--append-system` and `--vars` also accept `@file` or `@url`.

Template

diff --git a/docs/src/pages/prompts/sources-api.mdx b/docs/src/pages/prompts/sources-api.mdx index aeeecca2..19a1fa88 100644 --- a/docs/src/pages/prompts/sources-api.mdx +++ b/docs/src/pages/prompts/sources-api.mdx @@ -19,13 +19,15 @@ The prompts UI and Clicky operation surface are backed by a prompt entity. The e Captain discovers prompt sources in this order: 1. Embedded examples from `pkg/ai/prompt/testdata`, exposed as a read-only source. -2. Directories configured under `prompts.dirs` in `~/.captain.yaml`. -3. Directories passed to `captain serve --prompt-dir`. -4. An implicit writable local source at `.captain/prompts` when no other writable source exists. +2. Built-in prompts from `pkg/ai/prompt/builtin` (source id `builtin`), exposed as a read-only source. These are the document review prompts `spec-internal-high`, `spec-internal-low`, `spec-public-high`, `spec-public-low` and `proposal-review`. +3. Directories configured under `prompts.dirs` in `~/.captain.yaml`. +4. Directories passed to `captain serve --prompt-dir`. +5. An implicit writable local source at `.captain/prompts` when no other writable source exists. +6. An implicit writable local source at `~/.config/captain/prompts`, or `$XDG_CONFIG_HOME/captain/prompts` when that variable is set. It is listed even when the directory does not exist yet, and it never replaces `.captain/prompts` as the default save target. Embedded prompts are read-only. Saving an embedded prompt from the workbench writes a local fork, stripping the embedded walk root so `testdata/commit.prompt` becomes `commit.prompt`. -CLI prompt commands accept an opaque prompt ID, an explicit file path, or a bare filename with or without the `.prompt` extension. Bare filenames are resolved across the discovered sources. An existing file in the current directory takes precedence; if more than one discovered source contains the same filename, Captain reports the ambiguity and requires an ID or explicit path. +CLI prompt commands accept an opaque prompt ID, an explicit file path, or a bare filename with or without the `.prompt` extension. Bare filenames are resolved across the discovered sources. An existing file in the current directory takes precedence. A local prompt shadows an embedded one with the same name, so copying `spec-internal-high.prompt` into `~/.config/captain/prompts/` customizes it everywhere. If more than one local source contains the same filename, Captain reports the ambiguity and requires an ID or explicit path. ## Entity records diff --git a/pkg/api/preset_order_ginkgo_test.go b/pkg/api/preset_order_ginkgo_test.go new file mode 100644 index 00000000..4075e7cf --- /dev/null +++ b/pkg/api/preset_order_ginkgo_test.go @@ -0,0 +1,37 @@ +package api + +import ( + "math" + + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("Preset order", func() { + It("orders presets around prompt and request layers while retaining scope order for ties", func() { + layers := []SpecLayer{ + {Name: "late", Scope: SpecLayerContext, Order: math.MaxInt, Spec: Spec{Prompt: Prompt{System: "lint"}}}, + RequestSpecLayer("request", Spec{Prompt: Prompt{System: "request"}}), + PromptSpecLayer("prompt", Spec{Prompt: Prompt{System: "prompt"}}), + {Name: "early", Scope: SpecLayerUser, Order: math.MinInt}, + {Name: "default", Scope: SpecLayerContext}, + {Name: "second default", Scope: SpecLayerContext}, + } + resolved, err := ComposeSpecLayers(ResolveSpecOptions{Layers: layers}) + Expect(err).NotTo(HaveOccurred()) + names := make([]string, len(resolved.Trace)) + for i, layer := range resolved.Trace { + names[i] = layer.Name + } + Expect(names).To(Equal([]string{"early", "default", "second default", "prompt", "request", "late"})) + Expect(resolved.Spec.Prompt.System).To(Equal("lint")) + Expect(layers[0].Name).To(Equal("late")) + }) + + It("carries preset order into its resolved layers", func() { + preset := RuntimePreset{ID: "lint", Name: "Lint", Scope: SpecLayerContext, Order: 100} + layers, err := RuntimePresetLayers(RuntimePresetResolveRequest{Selected: []string{"lint"}, Presets: []RuntimePreset{preset}}) + Expect(err).NotTo(HaveOccurred()) + Expect(layers).To(Equal([]SpecLayer{{ID: "lint", Name: "Lint", Source: SpecLayerSourcePreset, Scope: SpecLayerContext, Order: 100}})) + }) +}) diff --git a/pkg/api/prompt_unmarshal.go b/pkg/api/prompt_unmarshal.go index d9cb05a5..c79e4cd7 100644 --- a/pkg/api/prompt_unmarshal.go +++ b/pkg/api/prompt_unmarshal.go @@ -25,6 +25,12 @@ func (p *Prompt) UnmarshalJSON(data []byte) error { if err := json.Unmarshal(data, &a); err != nil { return err } + // A JSON null on an opaque field is an explicit clear, not a value. + for _, raw := range []*json.RawMessage{&a.SchemaJSON, &a.InputSchemaJSON, &a.TypeSafeQuestions} { + if bytes.Equal(bytes.TrimSpace(*raw), []byte("null")) { + *raw = nil + } + } *p = Prompt(a) return nil } @@ -40,11 +46,13 @@ func (p *Prompt) UnmarshalYAML(value *yaml.Node) error { *p = Prompt{User: user} return nil } - type promptAlias Prompt - var a promptAlias - if err := value.Decode(&a); err != nil { + var fields any + if err := value.Decode(&fields); err != nil { return err } - *p = Prompt(a) - return nil + data, err := json.Marshal(fields) + if err != nil { + return err + } + return p.UnmarshalJSON(data) } diff --git a/pkg/api/prompt_yaml_schema_ginkgo_test.go b/pkg/api/prompt_yaml_schema_ginkgo_test.go new file mode 100644 index 00000000..64739e0f --- /dev/null +++ b/pkg/api/prompt_yaml_schema_ginkgo_test.go @@ -0,0 +1,25 @@ +package api + +import ( + "encoding/json" + + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" + "gopkg.in/yaml.v3" +) + +var _ = Describe("Prompt YAML schemas", func() { + It("decodes raw schema objects in reusable preset YAML without losing numeric constraints", func() { + var spec RuntimePresetSpec + Expect(yaml.Unmarshal([]byte("prompt:\n schemaJSON:\n type: object\n properties:\n count:\n type: integer\n maximum: 9007199254740993\n inputSchemaJSON:\n type: object\n typeSafeQuestions: null\n"), &spec)).To(Succeed()) + Expect(spec.Prompt.SchemaJSON).To(MatchJSON(`{"type":"object","properties":{"count":{"type":"integer","maximum":9007199254740993}}}`)) + Expect(spec.Prompt.InputSchemaJSON).To(MatchJSON(`{"type":"object"}`)) + Expect(spec.ToSpec().Fields()).To(HaveKey("/prompt/typeSafeQuestions")) + encoded, err := yaml.Marshal(spec) + Expect(err).NotTo(HaveOccurred()) + var again RuntimePresetSpec + Expect(yaml.Unmarshal(encoded, &again)).To(Succeed()) + Expect(json.Valid(again.Prompt.SchemaJSON)).To(BeTrue()) + Expect(again.Prompt.SchemaJSON).To(MatchJSON(spec.Prompt.SchemaJSON)) + }) +}) diff --git a/pkg/api/runtime_profiles.go b/pkg/api/runtime_profiles.go index 86e9add5..9d54c175 100644 --- a/pkg/api/runtime_profiles.go +++ b/pkg/api/runtime_profiles.go @@ -23,6 +23,7 @@ type RuntimePreset struct { Scope SpecLayerScope `json:"scope" yaml:"scope"` Spec RuntimePresetSpec `json:"spec" yaml:"spec"` Presets []string `json:"presets,omitempty" yaml:"presets,omitempty"` + Order int `json:"order,omitempty" yaml:"order,omitempty"` } type RuntimeProfile struct { @@ -77,7 +78,7 @@ func RuntimePresetLayers(request RuntimePresetResolveRequest) ([]SpecLayer, erro selected[preset.ID] = struct{}{} layers = append(layers, SpecLayer{ ID: preset.ID, Source: SpecLayerSourcePreset, - Name: preset.Name, Scope: preset.Scope, Spec: preset.Spec.ToSpec(), + Name: preset.Name, Scope: preset.Scope, Spec: preset.Spec.ToSpec(), Order: preset.Order, }) } if err := ValidateSpecLayers(layers...); err != nil { diff --git a/pkg/cli/runtime_entity_ginkgo_test.go b/pkg/cli/runtime_entity_ginkgo_test.go index 35bbf991..e445f3c9 100644 --- a/pkg/cli/runtime_entity_ginkgo_test.go +++ b/pkg/cli/runtime_entity_ginkgo_test.go @@ -166,7 +166,7 @@ var _ = Describe("runtime entities over file sources", func() { names = append(names, string(record.Source.Kind)+":"+record.Name) } Expect(names).To(Equal([]string{"file:Zeta", "builtin:Edit", "builtin:Plan", "builtin:Read-only"})) - Expect(listRuntimePresets(f.ctx, RuntimePresetListOptions{Source: "builtin"})).To(HaveLen(3)) + Expect(listRuntimePresets(f.ctx, RuntimePresetListOptions{Source: "builtin"})).To(HaveLen(4)) err = deleteRuntimePreset(f.ctx, "plan") Expect(statusOf(err)).To(Equal(http.StatusConflict)) diff --git a/pkg/cli/webapp/src/runtimeProfilesApi.test.ts b/pkg/cli/webapp/src/runtimeProfilesApi.test.ts index b24be117..6f6b8d83 100644 --- a/pkg/cli/webapp/src/runtimeProfilesApi.test.ts +++ b/pkg/cli/webapp/src/runtimeProfilesApi.test.ts @@ -6,6 +6,7 @@ import { fetchRuntimePresets, fetchRuntimeProfileResolution, fetchRuntimeProfiles, + presetWrite, resolveRuntimePresets, resolveRuntimeProfile, runtimeProfilesClient, @@ -36,6 +37,14 @@ const PRESET: StoredRuntimePreset = { updatedAt: "2026-09-01T10:00:00Z", }; +describe("preset order", () => { + it.each([0, 100, -100])("preserves authored order %s", (order) => { + expect(presetWrite({ ...PRESET, order })).toEqual({ + name: PRESET.name, scope: PRESET.scope, spec: PRESET.spec, presets: [], order, + }); + }); +}); + const PROFILE: StoredRuntimeProfile = { id: "profile-1", key: "review", diff --git a/pkg/cli/webapp/src/runtimeProfilesApi.ts b/pkg/cli/webapp/src/runtimeProfilesApi.ts index ce65e962..733d8688 100644 --- a/pkg/cli/webapp/src/runtimeProfilesApi.ts +++ b/pkg/cli/webapp/src/runtimeProfilesApi.ts @@ -38,7 +38,7 @@ export type StoredRuntimeProfile = RuntimeProfile & StoredRecord; export type RuntimePresetWrite = Pick< RuntimePreset, - "name" | "description" | "scope" | "spec" | "presets" + "name" | "description" | "scope" | "spec" | "presets" | "order" >; export type RuntimeProfileWrite = Pick< RuntimeProfile, @@ -49,6 +49,7 @@ export function presetWrite(preset: RuntimePreset): RuntimePresetWrite { return { name: preset.name, scope: preset.scope, + ...(preset.order !== undefined ? { order: preset.order } : {}), spec: preset.spec, presets: preset.presets ?? [], ...(preset.description !== undefined diff --git a/pkg/runtimeprofiles/README.md b/pkg/runtimeprofiles/README.md index f3b7b8a4..68a431e9 100644 --- a/pkg/runtimeprofiles/README.md +++ b/pkg/runtimeprofiles/README.md @@ -30,11 +30,11 @@ for _, warning := range resolved.Warnings { } ``` -`ResolveSpecLayers` composes in global → context → surface → user scope order, preserving order within a scope. It intersects restrictive catalogs, applies the strictest nonzero budget limits, and preserves raw layers in `Trace`. Compact model selectors retain their existing mode pin semantics: a prefix inside the effective model name wins over its sibling mode field. A higher layer's explicit effort overrides a lower compact effort and retains that higher layer's ownership. Model aliases and fallback names resolve only after composition. Final model, sandbox, and tool-policy refusals are errors; unsupported permission/resource capabilities produce separate `Warnings` for this compatibility release. The library never loads saved defaults from disk. Model-free compositions remain valid unless `RequireModel` is true; full execution admission still belongs to `promptrun.Preflight`. +`ResolveSpecLayers` composes in ascending explicit order, then global → context → surface → user scope order, preserving selection order for ties. It intersects restrictive catalogs, applies the strictest nonzero budget limits, and preserves raw layers in `Trace`. Compact model selectors retain their existing mode pin semantics: a prefix inside the effective model name wins over its sibling mode field. A higher layer's explicit effort overrides a lower compact effort and retains that higher layer's ownership. Model aliases and fallback names resolve only after composition. Final model, sandbox, and tool-policy refusals are errors; unsupported permission/resource capabilities produce separate `Warnings` for this compatibility release. The library never loads saved defaults from disk. Model-free compositions remain valid unless `RequireModel` is true; full execution admission still belongs to `promptrun.Preflight`. Use `api.ComposeSpecLayers` with the same `ResolveSpecOptions` for forms and defaults before a complete request exists. Its distinct `ComposedSpec` exposes `Spec`, `Trace`, `Provenance`, and `Warnings` without claiming runtime validity. It shares the same fold and saved-default pass as final resolution. Unknown authored models remain visible in composition; provider-specific defaults wait until a provider is known. Keep the authored layers when adding a request, then call `ResolveSpecLayers` once for the final stack. -An optional `Saved *captainconfig.AIDefaults` snapshot fills gaps after every authored layer. Provider mode and effort defaults apply independently to the final primary and each fallback. The global compact selector contributes its mode, effort, and fallback chain only within its provider family. Authored primary temperature/cache settings, and same-family effort, retain the existing fallback inheritance rules. File-wide temperature, cache, budget, timeout, and ambient-memory toggles remain run-wide. With a saved snapshot, a missing token budget uses Captain's existing 4096 default and missing effort uses the selected model's catalog default when one is declared. A nil snapshot injects neither saved nor built-in defaults, supporting catalog and authoritative snapshot consumers. +An optional `Saved *captainconfig.AIDefaults` snapshot fills gaps after every authored layer. Provider mode and effort defaults apply independently to the final primary and each fallback. The global compact selector contributes its mode, effort, and fallback chain only within its provider family. Authored primary temperature/cache settings, and same-family effort, retain the existing fallback inheritance rules. File-wide temperature, cache, budget, timeout, and ambient-memory toggles remain run-wide. With a saved snapshot, a missing token budget stays unset so the runtime applies its own default, and missing effort uses the selected model's catalog default when one is declared. A nil snapshot injects neither saved nor built-in defaults, supporting catalog and authoritative snapshot consumers. JSON/YAML decoding retains explicitly authored `false`, zero, empty lists/maps, and null values. Go callers mark intentional zero values with `spec.WithExplicit("/noCache", "/budget/cost", "/fallbacks")`; ordinary nonzero fields and scalar pointers already count as supplied. Paths use the serialized JSON-pointer vocabulary, including `/permissions/mcp/disabled` for the native MCP toggle. Merging replaces explicit clears, preserves unrelated groups, and removes stale presence when a list is replaced. `WithoutSession` removes both conversation data and its presence metadata. `Spec.DecodeFields` exposes the complete native shape so enclosing decoders retain their unknown-field policy; Captain prompt documents reject unknown declarations, while hosts can report them as warnings. @@ -48,13 +48,27 @@ Layer resolution checks every declared primary and fallback runtime. Execution p Catalog failures preserve ownership: `*runtimeprofiles.OwnedLayersError` wraps invalid stored data and missing nested preset references. An absent or ambiguous top-level profile remains `ErrNotFound` or `ErrAmbiguous`. `Resolver` additionally wraps selection failures in `*SelectionError`, recording whether the request, prompt pin, or configured default selected the profile. Use `errors.As` and `errors.Is` instead of parsing error text. +## Preset order + +Presets accept an integer `order`, defaulting to `0`. Layers merge in ascending `order`, then global → context → surface → user scope order, preserving selection order for ties. Negative values apply before ordinary layers; positive values apply after ordinary prompt and request layers. The value survives file and database storage, API writes, and resolution traces. A later layer can override fields from an earlier one. + +The built-in `Lint` preset uses `order: 100` and supplies `prompt.schemaJSON` plus `schemaStrictness: error`. It replaces authored output schemas while retaining the prompt body, input schema, model and other runtime settings: + +```sh +captain prompt run review.prompt --preset lint +captain prompt render review.prompt --preset lint --json +``` + +Its output is an object with a required `violations` array. Entries require `message`; optional fields are `file`, `line`, `column`, `severity` (`error`, `warning`, `info`), `rule` (`method`, `package`), `source`, and `code`. An empty array means no findings. Gavel's `lint prompt` command selects this preset automatically and renders the response as lint results. + ## Built-in presets -Captain ships three runtime presets, embedded from `builtin/presets/*.yaml` and served by `NewBuiltinSource` (source kind `builtin`, id `builtin`, label `Built-in`, read-only, no profiles). `NewDefaultCatalog` registers the built-in source last, including file-only catalogs, so it is the lowest-precedence source. All three use `scope: context`. +Captain ships runtime presets embedded from `builtin/presets/*.yaml` and served by `NewBuiltinSource` (source kind `builtin`, id `builtin`, label `Built-in`, read-only, no profiles). `NewDefaultCatalog` registers the built-in source last, including file-only catalogs, so a file or database preset with the same name takes precedence. Permission presets use `scope: context`; `Lint` uses `scope: surface` with `order: 100`. | Name | Spec | Notes | |---|---|---| | `Edit` | `permissions: {mode: acceptEdits, presets: [edit]}` | The same posture as `--edit`: acceptEdits plus the `edit` bundle. | +| `Lint` | `prompt.schemaJSON`, `prompt.schemaStrictness: error` | Structured lint findings; applies after ordinary prompt and request layers. | | `Plan` | `permissions: {mode: plan, tools: {read: allow, shell: deny}}` | Edit and write stay available so the runtime's native plan mode can write its plan file. Sets no web policy. | | `Read-only` | `permissions: {tools: {edit: deny, write: deny, shell: deny, web_search: deny, web_fetch: deny}}` | Sets no mode, so it combines with any posture; it blocks plan files too. Sets no read policy. | diff --git a/pkg/runtimeprofiles/builtin/presets/lint.yaml b/pkg/runtimeprofiles/builtin/presets/lint.yaml new file mode 100644 index 00000000..eb15637a --- /dev/null +++ b/pkg/runtimeprofiles/builtin/presets/lint.yaml @@ -0,0 +1,52 @@ +name: Lint +description: Return structured lint violations with file locations, rules and severity. +scope: surface +order: 100 +spec: + prompt: + outputSchemaType: json-schema + typeSafeQuestions: null + schemaStrictness: error + schemaJSON: + type: object + additionalProperties: false + required: [violations] + properties: + violations: + type: array + description: Findings from the review. Return an empty array when there are no findings. + items: + type: object + additionalProperties: false + required: [message] + properties: + file: + type: string + description: Path relative to the working directory. Omit for repository-wide findings. + line: + type: integer + minimum: 0 + column: + type: integer + minimum: 0 + message: + type: string + minLength: 1 + description: Explain the problem and its concrete fix. + severity: + type: string + enum: [error, warning, info] + description: Omitted severity is an error. + rule: + type: object + additionalProperties: false + properties: + method: + type: string + description: Stable rule identifier. + package: + type: string + source: + type: string + code: + type: string diff --git a/pkg/runtimeprofiles/layers_ginkgo_test.go b/pkg/runtimeprofiles/layers_ginkgo_test.go index b9a3c8b3..481ff90c 100644 --- a/pkg/runtimeprofiles/layers_ginkgo_test.go +++ b/pkg/runtimeprofiles/layers_ginkgo_test.go @@ -7,6 +7,16 @@ import ( ) var _ = Describe("Catalog layers", func() { + It("round trips preset order through YAML and catalog projections", func(ctx SpecContext) { + source := presetDir(GinkgoT().TempDir(), true) + created, err := source.Presets().Create(ctx, PresetInput{Name: "Ordered", Scope: api.SpecLayerContext, Order: 100}) + Expect(err).NotTo(HaveOccurred()) + reloaded, err := source.Presets().Get(ctx, created.Key) + Expect(err).NotTo(HaveOccurred()) + Expect(reloaded.Order).To(Equal(100)) + Expect(reloaded.API().Order).To(Equal(100)) + }) + It("materialises an ordered flat preset selection without a profile", func(ctx SpecContext) { source := newMemSource("db", SourceDB, true) organization := source.presets.put("organization", globalPreset("Organization")) diff --git a/pkg/runtimeprofiles/types.go b/pkg/runtimeprofiles/types.go index 08875bb1..cf0f4a1a 100644 --- a/pkg/runtimeprofiles/types.go +++ b/pkg/runtimeprofiles/types.go @@ -57,11 +57,12 @@ type Preset struct { Spec api.RuntimePresetSpec `json:"spec"` Presets []string `json:"presets"` UpdatedAt time.Time `json:"updatedAt"` + Order int `json:"order,omitempty" yaml:"order,omitempty"` } // API projects the preset onto the resolver's input type. func (p Preset) API() api.RuntimePreset { - return api.RuntimePreset{ID: p.ID, Name: p.Name, Description: p.Description, Scope: p.Scope, Spec: p.Spec, Presets: slices.Clone(p.Presets)} + return api.RuntimePreset{ID: p.ID, Name: p.Name, Description: p.Description, Scope: p.Scope, Spec: p.Spec, Presets: slices.Clone(p.Presets), Order: p.Order} } // Profile is a task-specific spec plus the ordered preset references (ids or @@ -92,6 +93,7 @@ type PresetInput struct { Scope api.SpecLayerScope `json:"scope" yaml:"scope"` Spec api.RuntimePresetSpec `json:"spec,omitempty" yaml:"spec,omitempty"` Presets []string `json:"presets,omitempty" yaml:"presets,omitempty"` + Order int `json:"order,omitempty" yaml:"order,omitempty"` } // ProfileInput is everything a caller authors for a profile; see PresetInput. @@ -191,7 +193,7 @@ func (in PresetInput) validate() error { if name == "" { return fmt.Errorf("%w: preset name is required", ErrInvalid) } - preset := api.RuntimePreset{ID: name, Name: name, Scope: in.Scope, Spec: in.Spec, Presets: in.Presets} + preset := api.RuntimePreset{ID: name, Name: name, Scope: in.Scope, Spec: in.Spec, Presets: in.Presets, Order: in.Order} if err := api.ValidateRuntimePreset(preset); err != nil { return fmt.Errorf("%w: %w", ErrInvalid, err) } @@ -201,7 +203,7 @@ func (in PresetInput) validate() error { func (in PresetInput) build(meta recordMeta) Preset { return Preset{ ID: meta.ID, Key: meta.Key, Source: meta.Source, Name: in.Name, Description: in.Description, - Scope: in.Scope, Spec: in.Spec, Presets: slices.Clone(in.Presets), UpdatedAt: meta.UpdatedAt, + Scope: in.Scope, Spec: in.Spec, Presets: slices.Clone(in.Presets), UpdatedAt: meta.UpdatedAt, Order: in.Order, } } From fb721e025d3bde72984684b16db760b78ec5e7b0 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Thu, 22 Oct 2026 18:51:52 +0300 Subject: [PATCH 07/77] feat(cli): add portable permissions access and built-in review prompts Add a portable access level (--access read-only|full, permissions.access) that compiles per runtime into native posture: tool denies on claude, a read-only sandbox that never asks on codex, and plan mode on gemini. Add `captain permissions explain` to show the compiled posture per runtime, and `captain permissions convert` to rewrite a permissions block into the portable form, refusing any conversion that would loosen access. Ship the document review prompts as a read-only built-in source. A user copy in the config prompts directory shadows a built-in of the same name instead of making the name ambiguous. Expose --preset, --no-presets, --runtime-profile and --vars on prompt commands, and route prompt runs through a shared PromptInvocation so the CLI and HTTP paths resolve prompts the same way. BREAKING CHANGE: an unset max-tokens no longer defaults to a built-in 4096. It is left to the runtime's own default (0 = runtime default), so output length can change for prompts with no saved or frontmatter value. --- pkg/cli/ai_options.go | 35 ++- pkg/cli/ai_prompt_file_test.go | 6 +- pkg/cli/ai_runtime_flags.go | 12 +- pkg/cli/ai_test.go | 12 +- pkg/cli/permissions_access.go | 148 ++++++++++++ pkg/cli/permissions_access_ginkgo_test.go | 124 +++++++++++ pkg/cli/permissions_convert.go | 235 ++++++++++++++++++++ pkg/cli/permissions_matrix.go | 4 + pkg/cli/prompt_invocation.go | 42 ++++ pkg/cli/prompt_invocation_ginkgo_test.go | 88 ++++++++ pkg/cli/prompt_records.go | 5 + pkg/cli/prompt_render.go | 7 + pkg/cli/prompt_run.go | 47 ++-- pkg/cli/prompt_source.go | 15 +- pkg/cli/prompt_sources.go | 22 ++ pkg/cli/prompt_sources_ginkgo_test.go | 80 +++++++ pkg/cli/review_prompts_ginkgo_test.go | 91 ++++++++ pkg/cli/runtime_preset_entity.go | 9 +- pkg/cli/testdata/permissions_matrix_test.md | 14 ++ 19 files changed, 929 insertions(+), 67 deletions(-) create mode 100644 pkg/cli/permissions_access.go create mode 100644 pkg/cli/permissions_access_ginkgo_test.go create mode 100644 pkg/cli/permissions_convert.go create mode 100644 pkg/cli/prompt_invocation.go create mode 100644 pkg/cli/prompt_invocation_ginkgo_test.go create mode 100644 pkg/cli/prompt_sources_ginkgo_test.go create mode 100644 pkg/cli/review_prompts_ginkgo_test.go diff --git a/pkg/cli/ai_options.go b/pkg/cli/ai_options.go index 4052f5c7..a01fd5a4 100644 --- a/pkg/cli/ai_options.go +++ b/pkg/cli/ai_options.go @@ -88,7 +88,7 @@ type AIRuntimeOptions struct { // Effort and Temperature are NOT here: they describe the model and so live on // the embedded aiflags.ModelFlags, promoted through AIProviderOptions. // Redeclaring them would bind --effort twice and panic cobra at init. - MaxTokens int `flag:"max-tokens" help:"Maximum output tokens (unset = saved default or 4096; 0 = provider default)"` + MaxTokens int `flag:"max-tokens" help:"Maximum output tokens (unset = saved default, else the runtime's own default; 0 = runtime default)"` MaxTurns int `flag:"max-turns" help:"Max agent turns 0-100, 0 = provider default (agent mode)"` Resume string `flag:"resume" help:"Resume an existing session by id (agent and cli modes)"` @@ -96,6 +96,7 @@ type AIRuntimeOptions struct { AllowedTools []string `flag:"allowed-tools" help:"Override --edit's built-in allowlist (claude only)"` DisallowedTools []string `flag:"disallowed-tools" help:"Tools to deny (claude only)"` PermissionMode string `flag:"permission-mode" help:"acceptEdits|auto|bypassPermissions|default|plan"` + Access string `flag:"access" help:"Portable access contract compiled per runtime: read-only|full"` // Perms is nil when --perms was not passed, which selects the host's // AIRuntimeResolveOptions.DefaultPerms; a non-nil selection whose entries // are all blank (`--perms ''`) selects none. @@ -128,28 +129,26 @@ func validatePermissionMode(s string) error { type AIPromptOptions struct { AIRuntimeOptions - // File is a positional .prompt template path rendered through pkg/ai/prompt. - // The frontmatter sets model + any ai.Request option; the body is the prompt. - File string `args:"true" help:"Path to a .prompt template to render"` - Prompt string `flag:"prompt" clicky:"cli-file-read" help:"Prompt text, or @file to load and render a .prompt template" short:"p"` - System string `flag:"system" help:"System prompt" short:"s"` - AppendSystem string `flag:"append-system" help:"Append text to the default system prompt"` - Var []string `flag:"var" help:"Template variable key=value (repeatable)" short:"V"` - Attach []string `flag:"attach" help:"Attach a local path or URL (repeatable; RFC 4180 comma-separated values allowed)" short:"A"` - MultiModels []string `flag:"multi-models" help:"Run prompt once per runtime selector in parallel, e.g. cli:sonnet-5,cmux:opus (repeatable; comma-separated allowed)" short:"M"` - Timeout string `flag:"timeout" help:"Request timeout (default 120s; a relocating sandbox waits for the remote agent instead)"` - NoStream bool `flag:"no-stream" help:"Disable streaming; print only the final text to stdout"` - Presets []string - PresetsSet bool + File string `args:"true" help:"Prompt name, ID, .prompt path, or - for stdin"` + Prompt string `flag:"prompt" clicky:"cli-file-read" help:"Prompt text, or @file to load and render a .prompt template" short:"p"` + System string `flag:"system" clicky:"cli-file-read" help:"System prompt" short:"s"` + AppendSystem string `flag:"append-system" clicky:"cli-file-read" help:"Append text to the default system prompt"` + Var []string `flag:"var" help:"Template variable key=value (repeatable)" short:"V"` + Attach []string `flag:"attach" help:"Attach a local path or URL (repeatable; RFC 4180 comma-separated values allowed)" short:"A"` + MultiModels []string `flag:"multi-models" help:"Run prompt once per runtime selector in parallel, e.g. cli:sonnet-5,cmux:opus (repeatable; comma-separated allowed)" short:"M"` + Timeout string `flag:"timeout" help:"Request timeout (default 120s; a relocating sandbox waits for the remote agent instead)"` + NoStream bool `flag:"no-stream" help:"Disable streaming; print only the final text to stdout"` + Presets []string `flag:"preset" help:"Runtime preset layered into the prompt (repeatable)"` + NoPresets bool `flag:"no-presets" help:"Clear presets selected by prompt frontmatter"` + RequiredPresets []string `flag:"-" json:"-" yaml:"-"` + PresetsSet bool // RuntimeProfile is the catalog profile (id or name) `captain prompt // run|render --runtime-profile` used to layer beneath the frontmatter. It is // retained only to warn and no-op. - RuntimeProfile string + RuntimeProfile string `flag:"runtime-profile" help:"Deprecated and ignored; use --preset"` - // Vars is the --vars JSON object. Not a flag here for the same reason as - // RuntimeProfile. - Vars string + Vars string `flag:"vars" clicky:"cli-file-read" help:"JSON object of template variables (or @file.json)"` // PromptRef is the raw --prompt/-p value as typed, before an @reference was // expanded into the file's contents. The expansion is what makes `-p @file` diff --git a/pkg/cli/ai_prompt_file_test.go b/pkg/cli/ai_prompt_file_test.go index 23197314..07f7d87a 100644 --- a/pkg/cli/ai_prompt_file_test.go +++ b/pkg/cli/ai_prompt_file_test.go @@ -262,7 +262,7 @@ func TestResolveCLI_FrontmatterOverridesSaved(t *testing.T) { } } -func TestResolveCLI_BuiltinMaxTokens(t *testing.T) { +func TestResolveCLI_OmittedMaxTokensUsesRuntimeDefault(t *testing.T) { isolateSavedAI(t) base := baseFileReq() base.Budget.MaxTokens = 0 // frontmatter omitted it @@ -270,8 +270,8 @@ func TestResolveCLI_BuiltinMaxTokens(t *testing.T) { if err != nil { t.Fatal(err) } - if req.Budget.MaxTokens != 4096 { - t.Errorf("MaxTokens = %d, want built-in 4096", req.Budget.MaxTokens) + if req.Budget.MaxTokens != 0 { + t.Errorf("MaxTokens = %d, want 0 so the runtime applies its own default", req.Budget.MaxTokens) } } diff --git a/pkg/cli/ai_runtime_flags.go b/pkg/cli/ai_runtime_flags.go index 145451d8..e42c5b5f 100644 --- a/pkg/cli/ai_runtime_flags.go +++ b/pkg/cli/ai_runtime_flags.go @@ -18,7 +18,7 @@ func (o AIRuntimeOptions) WithExplicit(paths ...string) AIRuntimeOptions { var runtimeFlagFields = map[string]string{ "model": "/model", "mode": "/mode", "fallback": "/fallbacks", "effort": "/effort", "temperature": "/temperature", "no-cache": "/noCache", "budget": "/budget/cost", "max-tokens": "/budget/maxTokens", "max-turns": "/budget/maxTurns", "resume": "/sessionId", - "no-mcp": "/permissions/mcp/disabled", "permission-mode": "/permissions/mode", + "no-mcp": "/permissions/mcp/disabled", "permission-mode": "/permissions/mode", "access": "/permissions/access", "no-hooks": "/memory/skipHooks", "no-skills": "/memory/skipSkills", "no-user": "/memory/skipUser", "no-project": "/memory/skipProject", "no-memory": "/memory/skipMemory", "bare": "/memory/bare", "skill-dir": "/memory/skills", "timeout": "/budget/timeout", "system": "/prompt/system", "append-system": "/prompt/appendSystem", @@ -53,10 +53,14 @@ func (o AIRuntimeOptions) requestSpec() (api.Spec, error) { if err := validatePermissionMode(o.PermissionMode); err != nil { return api.Spec{}, err } + if access := api.AccessLevel(o.Access); !access.Valid() { + return api.Spec{}, fmt.Errorf("invalid --access %q (valid: read-only|full)", o.Access) + } permissions := api.Permissions{ - Mode: api.PermissionMode(o.PermissionMode), - Tools: api.ToolsFromLists(o.AllowedTools, o.DisallowedTools), - MCP: api.MCP{Disabled: o.NoMCP}, + Mode: api.PermissionMode(o.PermissionMode), + Access: api.AccessLevel(o.Access), + Tools: api.ToolsFromLists(o.AllowedTools, o.DisallowedTools), + MCP: api.MCP{Disabled: o.NoMCP}, } if o.Edit { permissions.Presets = []api.Preset{api.PresetEdit} diff --git a/pkg/cli/ai_test.go b/pkg/cli/ai_test.go index ef6db9cb..7266f8a8 100644 --- a/pkg/cli/ai_test.go +++ b/pkg/cli/ai_test.go @@ -44,8 +44,8 @@ func TestAIPromptOptions_Resolve_Defaults(t *testing.T) { if req.Prompt.User != "hello" { t.Errorf("Prompt = %q, want hello", req.Prompt.User) } - if req.Budget.MaxTokens != 4096 { - t.Errorf("MaxTokens = %d, want 4096 built-in default", req.Budget.MaxTokens) + if req.Budget.MaxTokens != 0 { + t.Errorf("MaxTokens = %d, want 0 so the runtime applies its own default", req.Budget.MaxTokens) } for name, got := range map[string]bool{ "NoMCP": req.Permissions.MCP.Disabled, "NoHooks": req.Memory.SkipHooks, "NoSkills": req.Memory.SkipSkills, @@ -283,7 +283,7 @@ prompts: } // TestAIRuntimeOptions_Resolve_MaxTokensPrecedence pins the flag > saved > -// built-in order, replacing the old magic-4096 sentinel. +// runtime-default order. func TestAIRuntimeOptions_Resolve_MaxTokensPrecedence(t *testing.T) { t.Run("explicit flag wins over saved", func(t *testing.T) { seedSavedAI(t, "ai:\n maxTokens: 16000\n") @@ -305,14 +305,14 @@ func TestAIRuntimeOptions_Resolve_MaxTokensPrecedence(t *testing.T) { t.Errorf("MaxTokens = %d, want 16000 (saved)", req.Budget.MaxTokens) } }) - t.Run("unset with no saved uses built-in 4096", func(t *testing.T) { + t.Run("unset with no saved leaves the runtime default", func(t *testing.T) { isolateSavedAI(t) req, err := runtimeRequestForTest(AIRuntimeOptions{}, api.Prompt{System: "", AppendSystem: "", User: "p"}) if err != nil { t.Fatal(err) } - if req.Budget.MaxTokens != 4096 { - t.Errorf("MaxTokens = %d, want 4096 (built-in)", req.Budget.MaxTokens) + if req.Budget.MaxTokens != 0 { + t.Errorf("MaxTokens = %d, want 0 (runtime default)", req.Budget.MaxTokens) } }) } diff --git a/pkg/cli/permissions_access.go b/pkg/cli/permissions_access.go new file mode 100644 index 00000000..155288a0 --- /dev/null +++ b/pkg/cli/permissions_access.go @@ -0,0 +1,148 @@ +package cli + +import ( + "context" + "fmt" + "strings" + + clickyapi "github.com/flanksource/clicky/api" + + "github.com/flanksource/captain/pkg/aiflags" + "github.com/flanksource/captain/pkg/api" +) + +// `captain permissions explain` shows what a prompt's permissions become on +// each runtime it may land on: the resolved access intent and the layer that +// set it, the compiled native posture per runtime, any refusal, and the +// portable form the converter suggests. + +type PermissionsExplainOptions struct { + Prompt string `args:"true" help:"Prompt name, ID or .prompt path"` + Models []string `flag:"model" help:"Runtime to explain for, e.g. agent:sonnet (repeatable); defaults to the prompt's own model"` + Presets []string `flag:"preset" help:"Runtime preset layered into the prompt (repeatable)"` +} + +type PermissionsExplainResult struct { + Prompt string `json:"prompt"` + Access *api.AccessState `json:"access,omitempty"` + Suggestion api.ConversionResult `json:"suggestion"` + Runtimes []PermissionsExplainRuntime `json:"runtimes"` +} + +// PermissionsExplainRuntime is one runtime's compiled posture, or why the run +// would be refused there. +type PermissionsExplainRuntime struct { + Model string `json:"model"` + Runtime string `json:"runtime,omitempty"` + Report *api.AccessReport `json:"report,omitempty"` + Refused string `json:"refused,omitempty"` + Warnings []string `json:"warnings,omitempty"` +} + +func RunPermissionsExplain(ctx context.Context, opts PermissionsExplainOptions) (any, error) { + if strings.TrimSpace(opts.Prompt) == "" { + return nil, fmt.Errorf("a prompt name, ID or .prompt path is required") + } + base, err := renderForExplain(ctx, opts, "") + if err != nil { + return nil, err + } + result := PermissionsExplainResult{Prompt: base.Name, Access: base.Resolution.Access, Suggestion: api.ConvertToAccess(base.Input)} + models := opts.Models + if len(models) == 0 { + models = []string{""} + } + for _, model := range models { + result.Runtimes = append(result.Runtimes, explainRuntime(ctx, opts, model, base)) + } + return result, nil +} + +func renderForExplain(ctx context.Context, opts PermissionsExplainOptions, model string) (PromptRenderResult, error) { + runtime := AIRuntimeOptions{AIProviderOptions: AIProviderOptions{ModelFlags: aiflags.ModelFlags{Model: model}}} + return RenderPrompt(ctx, PromptInvocation{Reference: opts.Prompt, Stdin: strings.NewReader(""), + Options: AIPromptOptions{AIRuntimeOptions: runtime, Presets: opts.Presets}}) +} + +func explainRuntime(ctx context.Context, opts PermissionsExplainOptions, model string, base PromptRenderResult) PermissionsExplainRuntime { + rendered := base + if model != "" { + var err error + if rendered, err = renderForExplain(ctx, opts, model); err != nil { + return PermissionsExplainRuntime{Model: model, Refused: err.Error()} + } + } + runtime := api.RuntimeOf(rendered.Config.Model.Provider, rendered.Config.Model.Mode) + entry := PermissionsExplainRuntime{Model: rendered.Config.Model.Name, Runtime: runtime.String(), Warnings: rendered.Resolution.Warnings} + _, report, err := api.CompileAccess(runtime, rendered.Input) + entry.Report = &report + switch { + case err != nil: + entry.Refused = err.Error() + case rendered.ValidationError != "": + entry.Refused = rendered.ValidationError + } + return entry +} + +func (r PermissionsExplainResult) Pretty() clickyapi.Text { + text := clickyapi.Text{}.Append(r.Prompt, "font-bold").NewLine() + if r.Access == nil { + text = text.Append("access: none (each runtime keeps its own rules)", "text-gray-500").NewLine() + } else { + text = text.Append(fmt.Sprintf("access: %s from %s (%s dialect) in layer %q", r.Access.Level, r.Access.Source, r.Access.Dialect, r.Access.Layer)).NewLine() + } + for _, runtime := range r.Runtimes { + text = text.NewLine().Append(runtime.Model+" ", "font-bold").Append(runtime.Runtime, "text-blue-400").NewLine() + text = text.Add(runtime.pretty()) + } + text = text.NewLine().Append("suggested portable form: ", "font-bold") + if !r.Suggestion.Convertible { + return text.Append(r.Suggestion.Reason, "text-gray-500") + } + text = text.Append(fmt.Sprintf("permissions: {access: %s}", r.Suggestion.Permissions.Access)) + for _, residual := range r.Suggestion.Residual { + text = text.NewLine().Append(" kept: "+residual, "text-gray-500") + } + return text +} + +func (r PermissionsExplainRuntime) pretty() clickyapi.Text { + text := clickyapi.Text{} + if r.Refused != "" { + text = text.Append(" refused: ", "text-red-500").Append(r.Refused).NewLine() + } + if report := r.Report; report != nil { + for _, line := range reportLines(*report) { + text = text.Append(" " + line).NewLine() + } + } + for _, warning := range r.Warnings { + text = text.Append(" warning: "+warning, "text-yellow-500").NewLine() + } + return text +} + +func reportLines(report api.AccessReport) []string { + var lines []string + add := func(label string, values ...string) { + if len(values) > 0 && values[0] != "" { + lines = append(lines, label+": "+strings.Join(values, ", ")) + } + } + add("dialect", string(report.Dialect)) + if report.Unchanged { + lines = append(lines, "unchanged: compiled in its own dialect") + } + add("denied tools", report.DeniedTools...) + add("sandbox", report.Sandbox) + add("approval", report.Approval) + add("mode", string(report.Mode)) + if report.MCPDisabled { + lines = append(lines, "mcp: disabled") + } + add("overridden", report.Overridden...) + add("equivalent", report.Equivalences...) + add("note", report.Notes...) + return lines +} diff --git a/pkg/cli/permissions_access_ginkgo_test.go b/pkg/cli/permissions_access_ginkgo_test.go new file mode 100644 index 00000000..62151a70 --- /dev/null +++ b/pkg/cli/permissions_access_ginkgo_test.go @@ -0,0 +1,124 @@ +package cli + +import ( + "context" + "os" + "path/filepath" + + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" + + "github.com/flanksource/captain/pkg/api" + "github.com/flanksource/captain/pkg/captainconfig" + "github.com/flanksource/captain/pkg/runtimeprofiles" +) + +const legacyReviewPrompt = `--- +description: A read-only review. +model: claude-sonnet-5 +mode: agent +permissions: + tools: + Read: allow + edit: deny + write: deny + shell: deny +memory: + skipUser: true +--- +Review {{files}}. +` + +var _ = Describe("--access", func() { + DescribeTable("lands on the request permissions", + func(flag string, want api.AccessLevel, wantErr string) { + spec, err := AIRuntimeOptions{Access: flag}.requestSpec() + if wantErr != "" { + Expect(err).To(MatchError(ContainSubstring(wantErr))) + return + } + Expect(err).NotTo(HaveOccurred()) + Expect(spec.Permissions.Access).To(Equal(want)) + }, + Entry("read-only", "read-only", api.AccessReadOnly, ""), + Entry("unset", "", api.AccessLevel(""), ""), + Entry("unknown", "readonly", api.AccessLevel(""), `invalid --access "readonly"`), + ) +}) + +var _ = Describe("captain permissions explain", func() { + It("shows the compiled posture of a review prompt on claude and codex", func() { + captainconfig.SetPathForTesting(filepath.Join(GinkgoT().TempDir(), "captain.yaml")) + DeferCleanup(func() { captainconfig.SetPathForTesting("") }) + catalog, err := runtimeprofiles.NewCatalog(runtimeprofiles.NewBuiltinSource()) + Expect(err).NotTo(HaveOccurred()) + ctx := ContextWithRuntimeCatalog(context.Background(), catalog) + + out, err := RunPermissionsExplain(ctx, PermissionsExplainOptions{Prompt: "proposal-review", + Models: []string{"agent:sonnet", "agent:gpt-6.1-sol"}, Presets: []string{"lint"}}) + Expect(err).NotTo(HaveOccurred()) + result := out.(PermissionsExplainResult) + + Expect(result.Access).To(Equal(&api.AccessState{Level: api.AccessReadOnly, Dialect: api.AccessDialectPortable, + Source: "permissions.access", Layer: result.Access.Layer})) + Expect(result.Runtimes).To(HaveLen(2)) + claude, codex := result.Runtimes[0], result.Runtimes[1] + Expect(claude.Refused).To(BeEmpty()) + Expect(claude.Runtime).To(Equal("anthropic agent")) + Expect(claude.Report.DeniedTools).To(ContainElements("Bash", "Edit", "Write", "Agent")) + Expect(codex.Refused).To(BeEmpty()) + Expect(codex.Runtime).To(Equal("openai agent")) + Expect(codex.Report.Sandbox).To(Equal("read-only")) + Expect(codex.Report.Approval).To(Equal("never")) + Expect(result.Suggestion.Reason).To(Equal("permissions.access is already read-only")) + }) +}) + +var _ = Describe("captain permissions convert", func() { + write := func(name, body string) string { + path := filepath.Join(GinkgoT().TempDir(), name) + Expect(os.WriteFile(path, []byte(body), 0o644)).To(Succeed()) + return path + } + + It("prints the portable form of a .prompt without writing it", func() { + path := write("review.prompt", legacyReviewPrompt) + + out, err := RunPermissionsConvert(PermissionsConvertOptions{File: path}) + Expect(err).NotTo(HaveOccurred()) + result := out.(PermissionsConvertResult) + + Expect(result.Diff).To(ContainSubstring("+ access: read-only\n")) + for _, dropped := range []string{"edit", "write", "shell"} { + Expect(result.Diff).To(ContainSubstring("- " + dropped + ": deny\n")) + Expect(result.Diff).NotTo(ContainSubstring("+ " + dropped + ": deny\n")) + } + Expect(result.Diff).NotTo(ContainSubstring("memory")) + Expect(result.Conversion.Residual).To(ConsistOf("permissions.tools Read: allow")) + Expect(result.Written).To(BeFalse()) + Expect(os.ReadFile(path)).To(Equal([]byte(legacyReviewPrompt))) + }) + + It("rewrites the read-only preset in place with its web denies kept", func() { + preset, err := os.ReadFile("../runtimeprofiles/builtin/presets/read-only.yaml") + Expect(err).NotTo(HaveOccurred()) + path := write("read-only.yaml", string(preset)) + + out, err := RunPermissionsConvert(PermissionsConvertOptions{File: path, Write: true}) + Expect(err).NotTo(HaveOccurred()) + Expect(out.(PermissionsConvertResult).Conversion.Residual).To(ConsistOf( + "permissions.tools web_fetch: deny", "permissions.tools web_search: deny")) + + converted, err := os.ReadFile(path) + Expect(err).NotTo(HaveOccurred()) + Expect(string(converted)).To(ContainSubstring("spec:\n permissions:\n access: read-only\n tools:\n web_fetch: deny\n web_search: deny\n")) + Expect(string(converted)).To(HavePrefix("name: Read-only\n")) + }) + + It("refuses a block that is not read-only, with the reason", func() { + path := write("plan.yaml", "spec:\n permissions:\n mode: plan\n tools:\n read: allow\n shell: deny\n") + + _, err := RunPermissionsConvert(PermissionsConvertOptions{File: path}) + Expect(err).To(MatchError(ContainSubstring("not converted: permissions.mode plan permits the plan-file write"))) + }) +}) diff --git a/pkg/cli/permissions_convert.go b/pkg/cli/permissions_convert.go new file mode 100644 index 00000000..be718cba --- /dev/null +++ b/pkg/cli/permissions_convert.go @@ -0,0 +1,235 @@ +package cli + +import ( + "bytes" + "fmt" + "os" + "strings" + + clickyapi "github.com/flanksource/clicky/api" + "github.com/sergi/go-diff/diffmatchpatch" + "gopkg.in/yaml.v3" + + "github.com/flanksource/captain/pkg/api" +) + +// `captain permissions convert` rewrites a prompt's or preset's permissions +// block into the portable access form, only when the conversion is exact or +// tighter. It prints the diff and writes nothing unless --write is passed; a +// conversion that would loosen anything is refused with the reason. + +type PermissionsConvertOptions struct { + File string `args:"true" help:"A .prompt file or runtime preset YAML file"` + Write bool `flag:"write" help:"Rewrite the file in place instead of only printing the diff"` +} + +type PermissionsConvertResult struct { + File string `json:"file"` + Conversion api.ConversionResult `json:"conversion"` + Diff string `json:"diff"` + Written bool `json:"written"` +} + +func RunPermissionsConvert(opts PermissionsConvertOptions) (any, error) { + if strings.TrimSpace(opts.File) == "" { + return nil, fmt.Errorf("a .prompt or preset file is required") + } + before, err := os.ReadFile(opts.File) + if err != nil { + return nil, err + } + conversion, after, err := convertPermissionsDocument(string(before)) + if err != nil { + return nil, fmt.Errorf("%s: %w", opts.File, err) + } + result := PermissionsConvertResult{File: opts.File, Conversion: conversion, Diff: lineDiff(string(before), after)} + if opts.Write { + info, err := os.Stat(opts.File) + if err != nil { + return nil, err + } + if err := os.WriteFile(opts.File, []byte(after), info.Mode().Perm()); err != nil { + return nil, err + } + result.Written = true + } + return result, nil +} + +// yamlSegment is the YAML part of a document: a .prompt file's frontmatter or +// a whole preset file, with the line it starts on. +type yamlSegment struct { + lines []string + start int + end int + mapped *yaml.Node +} + +// convertPermissionsDocument converts the document's permissions (and, for the +// sandbox dialect, its sandbox) and splices the rewritten blocks into the +// original text, so every other line keeps its formatting and comments. +func convertPermissionsDocument(document string) (api.ConversionResult, string, error) { + segment, err := parseYAMLSegment(document) + if err != nil { + return api.ConversionResult{}, "", err + } + spec, err := segment.permissionsSpec() + if err != nil { + return api.ConversionResult{}, "", err + } + conversion := api.ConvertToAccess(spec) + if !conversion.Convertible { + return conversion, "", fmt.Errorf("not converted: %s", conversion.Reason) + } + replacements := map[string]any{"permissions": conversion.Permissions} + if conversion.Dialect == api.AccessDialectSandbox { + replacements["sandbox"] = conversion.Sandbox + } + lines, err := segment.replaceKeys(replacements) + if err != nil { + return api.ConversionResult{}, "", err + } + return conversion, strings.Join(lines, "\n"), nil +} + +func parseYAMLSegment(document string) (yamlSegment, error) { + lines := strings.Split(document, "\n") + segment := yamlSegment{lines: lines, start: 0, end: len(lines)} + if len(lines) > 0 && strings.TrimSpace(lines[0]) == "---" { + closing := -1 + for i := 1; i < len(lines); i++ { + if strings.TrimSpace(lines[i]) == "---" { + closing = i + break + } + } + if closing < 0 { + return yamlSegment{}, fmt.Errorf("frontmatter opened with --- is never closed") + } + segment.start, segment.end = 1, closing + } + var root yaml.Node + if err := yaml.Unmarshal([]byte(strings.Join(lines[segment.start:segment.end], "\n")), &root); err != nil { + return yamlSegment{}, fmt.Errorf("decode YAML: %w", err) + } + if len(root.Content) == 0 || root.Content[0].Kind != yaml.MappingNode { + return yamlSegment{}, fmt.Errorf("expected a YAML mapping") + } + segment.mapped = root.Content[0] + // A runtime preset nests its spec under `spec:`; a .prompt keeps it at the top. + if spec := mappingChild(segment.mapped, "spec"); spec != nil && spec.Kind == yaml.MappingNode { + segment.mapped = spec + } + return segment, nil +} + +func (s yamlSegment) permissionsSpec() (api.Spec, error) { + var spec api.Spec + node := mappingChild(s.mapped, "permissions") + if node == nil { + return spec, fmt.Errorf("no permissions block to convert") + } + if err := node.Decode(&spec.Permissions); err != nil { + return spec, fmt.Errorf("decode permissions: %w", err) + } + if sandbox := mappingChild(s.mapped, "sandbox"); sandbox != nil { + spec.Sandbox = &api.SandboxRef{} + if err := sandbox.Decode(spec.Sandbox); err != nil { + return spec, fmt.Errorf("decode sandbox: %w", err) + } + } + return spec, nil +} + +// replaceKeys rewrites each named key's block in place, working from the +// bottom of the document up so earlier line numbers stay valid. +func (s yamlSegment) replaceKeys(values map[string]any) ([]string, error) { + lines := append([]string(nil), s.lines...) + content := s.mapped.Content + for i := len(content) - 2; i >= 0; i -= 2 { + value, ok := values[content[i].Value] + if !ok { + continue + } + first := s.start + content[i].Line - 1 + last := s.end + if i+2 < len(content) { + last = s.start + content[i+2].Line - 1 + } + for last > first+1 && strings.TrimSpace(lines[last-1]) == "" { + last-- + } + block, err := yamlBlock(content[i].Value, value, content[i].Column-1) + if err != nil { + return nil, err + } + lines = append(lines[:first], append(block, lines[last:]...)...) + } + return lines, nil +} + +func yamlBlock(key string, value any, indent int) ([]string, error) { + var buf bytes.Buffer + encoder := yaml.NewEncoder(&buf) + encoder.SetIndent(2) + if err := encoder.Encode(map[string]any{key: value}); err != nil { + return nil, fmt.Errorf("encode %s: %w", key, err) + } + if err := encoder.Close(); err != nil { + return nil, err + } + block := strings.Split(strings.TrimRight(buf.String(), "\n"), "\n") + for i := range block { + block[i] = strings.Repeat(" ", indent) + block[i] + } + return block, nil +} + +func mappingChild(mapping *yaml.Node, key string) *yaml.Node { + for i := 0; i+1 < len(mapping.Content); i += 2 { + if mapping.Content[i].Value == key { + return mapping.Content[i+1] + } + } + return nil +} + +// lineDiff renders the changed lines only, prefixed - and +. +func lineDiff(before, after string) string { + dmp := diffmatchpatch.New() + left, right, lines := dmp.DiffLinesToChars(before, after) + var out strings.Builder + for _, diff := range dmp.DiffCharsToLines(dmp.DiffMain(left, right, false), lines) { + prefix := map[diffmatchpatch.Operation]string{diffmatchpatch.DiffDelete: "-", diffmatchpatch.DiffInsert: "+"}[diff.Type] + if prefix == "" { + continue + } + for _, line := range strings.SplitAfter(diff.Text, "\n") { + if line != "" { + out.WriteString(prefix + strings.TrimSuffix(line, "\n") + "\n") + } + } + } + return out.String() +} + +func (r PermissionsConvertResult) Pretty() clickyapi.Text { + text := clickyapi.Text{}.Append(r.File, "font-bold").NewLine() + for _, line := range strings.Split(strings.TrimRight(r.Diff, "\n"), "\n") { + style := "text-green-500" + if strings.HasPrefix(line, "-") { + style = "text-red-500" + } + text = text.Append(line, style).NewLine() + } + for _, dropped := range r.Conversion.Dropped { + text = text.Append("implied by read-only: "+dropped, "text-gray-500").NewLine() + } + for _, residual := range r.Conversion.Residual { + text = text.Append("kept beside access: "+residual, "text-gray-500").NewLine() + } + if !r.Written { + text = text.Append("not written; pass --write to rewrite the file", "text-gray-500") + } + return text +} diff --git a/pkg/cli/permissions_matrix.go b/pkg/cli/permissions_matrix.go index e3a6ff17..dcae141b 100644 --- a/pkg/cli/permissions_matrix.go +++ b/pkg/cli/permissions_matrix.go @@ -249,6 +249,10 @@ func matrixSettings(provenance api.ToolProvenance) []matrixSetting { func(c api.PermissionCapabilities) api.Support { return c.ResourceSupport(kind, mode) }}) } } + for _, level := range api.AllAccessLevels() { + out = append(out, matrixSetting{"access " + string(level), + func(c api.PermissionCapabilities) api.Support { return c.AccessSupport(level) }}) + } return out } diff --git a/pkg/cli/prompt_invocation.go b/pkg/cli/prompt_invocation.go new file mode 100644 index 00000000..64961239 --- /dev/null +++ b/pkg/cli/prompt_invocation.go @@ -0,0 +1,42 @@ +package cli + +import ( + "context" + "errors" + "io" +) + +// PromptInvocation runs the same prompt sources and runtime options as the CLI. +type PromptInvocation struct { + Reference string + Options AIPromptOptions + Stdin io.Reader +} + +func RenderPrompt(ctx context.Context, invocation PromptInvocation) (PromptRenderResult, error) { + var stdin string + var err error + if invocation.Stdin == nil { + stdin, err = readStdinIfCLI(ctx) + } else { + var data []byte + data, err = io.ReadAll(invocation.Stdin) + stdin = string(data) + } + if err != nil { + return PromptRenderResult{}, err + } + return renderPromptCLI(ctx, invocation.Reference, invocation.Options, invocation.Options.Vars, stdin) +} + +func RunPrompt(ctx context.Context, invocation PromptInvocation) (PromptRunResult, error) { + rendered, err := RenderPrompt(ctx, invocation) + if err != nil { + return PromptRunResult{}, err + } + if rendered.ValidationError != "" { + return PromptRunResult{}, errors.New(rendered.ValidationError) + } + logRuntimeWarnings(rendered.Resolution.Warnings) + return executeSyncRun(ctx, rendered, invocation.Options) +} diff --git a/pkg/cli/prompt_invocation_ginkgo_test.go b/pkg/cli/prompt_invocation_ginkgo_test.go new file mode 100644 index 00000000..b5b75001 --- /dev/null +++ b/pkg/cli/prompt_invocation_ginkgo_test.go @@ -0,0 +1,88 @@ +package cli + +import ( + "context" + "os" + "path/filepath" + "strings" + + "github.com/flanksource/captain/pkg/api" + "github.com/flanksource/captain/pkg/captainconfig" + "github.com/flanksource/captain/pkg/runtimeprofiles" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("Prompt invocation", func() { + var ctx context.Context + + BeforeEach(func() { + captainconfig.SetPathForTesting(filepath.Join(GinkgoT().TempDir(), "captain.yaml")) + DeferCleanup(func() { captainconfig.SetPathForTesting("") }) + catalog, err := runtimeprofiles.NewCatalog(runtimeprofiles.NewBuiltinSource()) + Expect(err).NotTo(HaveOccurred()) + ctx = ContextWithRuntimeCatalog(context.Background(), catalog) + }) + + It("applies the lint preset after authored output schemas for every runtime", func() { + path := filepath.Join(GinkgoT().TempDir(), "review.prompt") + Expect(os.WriteFile(path, []byte("---\nmodel: api:sonnet\nruntimes: [api:sonnet, api:haiku]\noutput:\n schema:\n old: string\n---\nReview {{change}}"), 0o600)).To(Succeed()) + rendered, err := RenderPrompt(ctx, PromptInvocation{Reference: path, Stdin: strings.NewReader("diff"), Options: AIPromptOptions{ + RequiredPresets: []string{"lint"}, Var: []string{"change=-"}, + }}) + Expect(err).NotTo(HaveOccurred()) + Expect(rendered.ValidationError).To(BeEmpty()) + Expect(rendered.Input.Prompt.User).To(Equal("Review diff")) + Expect(rendered.variants).To(HaveLen(2)) + for _, variant := range rendered.variants { + Expect(variant.Request.Prompt.SchemaJSON).To(ContainSubstring(`"violations"`)) + Expect(variant.Request.Prompt.SchemaJSON).NotTo(ContainSubstring(`"old"`)) + Expect(variant.Request.Prompt.SchemaStrictness).To(Equal(api.SchemaStrictnessError)) + Expect(variant.Resolution.Trace[len(variant.Resolution.Trace)-1].Name).To(Equal("Lint")) + } + }) + + DescribeTable("supports Captain input sources", + func(reference, prompt, stdin, expected string) { + rendered, err := RenderPrompt(ctx, PromptInvocation{Reference: reference, Stdin: strings.NewReader(stdin), Options: AIPromptOptions{ + Prompt: prompt, RequiredPresets: []string{"lint"}, + }}) + Expect(err).NotTo(HaveOccurred()) + Expect(rendered.Input.Prompt.User).To(Equal(expected)) + Expect(rendered.Input.Prompt.SchemaJSON).To(ContainSubstring(`"violations"`)) + }, + Entry("inline", "", "Review the change", "", "Review the change"), + Entry("stdin", "-", "", "Review piped content", "Review piped content"), + ) + + It("replaces TypeSafe output questions while preserving the input schema", func() { + path := filepath.Join(GinkgoT().TempDir(), "review.prompt") + Expect(os.WriteFile(path, []byte(`--- +model: api:sonnet +input: + schemaType: json-schema + schema: + type: object + required: [change] + properties: + change: + type: string +output: + schemaType: typesafe-schema + schema: + valid: + type: noul + instructions: Is this change valid? +--- +Review {{change}}`), 0o600)).To(Succeed()) + rendered, err := RenderPrompt(ctx, PromptInvocation{Reference: path, Stdin: strings.NewReader("diff"), Options: AIPromptOptions{ + RequiredPresets: []string{"lint"}, Var: []string{"change=-"}, NoPresets: true, + }}) + Expect(err).NotTo(HaveOccurred()) + Expect(rendered.ValidationError).To(BeEmpty()) + Expect(rendered.Input.Prompt.InputSchemaJSON).To(ContainSubstring(`"change"`)) + Expect(rendered.Input.Prompt.TypeSafeQuestions).To(BeEmpty()) + Expect(rendered.Input.Prompt.OutputSchemaType).To(Equal(api.SchemaTypeJSONSchema)) + Expect(rendered.Input.Prompt.SchemaJSON).To(ContainSubstring(`"violations"`)) + }) +}) diff --git a/pkg/cli/prompt_records.go b/pkg/cli/prompt_records.go index 237f7ff8..314149b8 100644 --- a/pkg/cli/prompt_records.go +++ b/pkg/cli/prompt_records.go @@ -9,6 +9,7 @@ import ( "maps" "os" "path/filepath" + "slices" "sort" "strings" @@ -149,6 +150,10 @@ func resolvePromptRecordByName(sources []promptSource, name string) (promptRecor } } } + // A local copy of a shipped prompt overrides it rather than making the name ambiguous. + if slices.ContainsFunc(matches, func(record promptRecord) bool { return record.Source.Kind != "embedded" }) { + matches = slices.DeleteFunc(matches, func(record promptRecord) bool { return record.Source.Kind == "embedded" }) + } switch len(matches) { case 0: return promptRecord{}, fmt.Errorf("prompt %q not found", name) diff --git a/pkg/cli/prompt_render.go b/pkg/cli/prompt_render.go index 9c851dc6..3893861c 100644 --- a/pkg/cli/prompt_render.go +++ b/pkg/cli/prompt_render.go @@ -2,6 +2,7 @@ package cli import ( "context" + "encoding/json" "fmt" "os" "strings" @@ -170,6 +171,12 @@ func completePromptRender(input promptRenderInput) (PromptRenderResult, error) { } result.Resolution.Warnings = append(input.Warnings, result.Resolution.Warnings...) req, cfg := result.Request, result.Config + if len(req.Prompt.SchemaJSON) > 0 { + if err := json.Unmarshal(req.Prompt.SchemaJSON, &detail.OutputSchema); err != nil { + return PromptRenderResult{}, fmt.Errorf("decode resolved output schema: %w", err) + } + detail.OutputSchemaType = api.SchemaTypeJSONSchema + } return PromptRenderResult{ ID: detail.ID, Name: detail.Name, Model: cfg.Model.Name, Provider: providerName(cfg.Model.Provider), Mode: string(cfg.Model.Mode), User: req.Prompt.User, System: req.Prompt.System, Input: req, Config: cfg, diff --git a/pkg/cli/prompt_run.go b/pkg/cli/prompt_run.go index e2f00909..0ab3928c 100644 --- a/pkg/cli/prompt_run.go +++ b/pkg/cli/prompt_run.go @@ -45,39 +45,25 @@ type PromptRunSummary struct { // prompt` is a deprecated alias. func runPromptAction(ctx context.Context, id string, flags map[string]string) (PromptRunResult, error) { _, isHTTP := clickyrpc.RequestFromContext(ctx) - - var rendered PromptRenderResult - var opts AIPromptOptions - var chatRequested bool - if isHTTP { - req, err := readRenderRequest(ctx, flags) - if err != nil { - return PromptRunResult{}, err - } - if rendered, err = renderPrompt(ctx, id, req); err != nil { - return PromptRunResult{}, err - } - chatRequested = req.Chat - } else { - var err error - if opts, err = actionFlagsToOptions(flags); err != nil { - return PromptRunResult{}, err - } - stdin, err := readStdinIfCLI(ctx) + if !isHTTP { + opts, err := actionFlagsToOptions(flags) if err != nil { return PromptRunResult{}, err } - if rendered, err = renderPromptCLI(ctx, id, opts, opts.Vars, stdin); err != nil { - return PromptRunResult{}, err - } + return RunPrompt(ctx, PromptInvocation{Reference: id, Options: opts}) + } + req, err := readRenderRequest(ctx, flags) + if err != nil { + return PromptRunResult{}, err + } + rendered, err := renderPrompt(ctx, id, req) + if err != nil { + return PromptRunResult{}, err } if rendered.ValidationError != "" { return PromptRunResult{}, errors.New(rendered.ValidationError) } - if !isHTTP { - logRuntimeWarnings(rendered.Resolution.Warnings) - } - if chatRequested { + if req.Chat { if rendered.Input.Prompt.HasSchema() { return PromptRunResult{}, errors.New("chat mode does not support structured-output prompts") } @@ -86,13 +72,10 @@ func runPromptAction(ctx context.Context, id string, flags map[string]string) (P } } - if isHTTP { - if len(rendered.Runtimes) > 0 { - return launchAsyncBatch(ctx, id, rendered, rendered.Runtimes, chatRequested) - } - return launchAsyncRun(id, rendered, chatRequested) + if len(rendered.Runtimes) > 0 { + return launchAsyncBatch(ctx, id, rendered, rendered.Runtimes, req.Chat) } - return executeSyncRun(ctx, rendered, opts) + return launchAsyncRun(id, rendered, req.Chat) } var executePromptRequestFunc = executePromptRequest diff --git a/pkg/cli/prompt_source.go b/pkg/cli/prompt_source.go index 6a6538a8..1d963386 100644 --- a/pkg/cli/prompt_source.go +++ b/pkg/cli/prompt_source.go @@ -7,6 +7,7 @@ import ( "io" "os" "regexp" + "slices" "strconv" "strings" @@ -15,6 +16,7 @@ import ( "github.com/flanksource/captain/pkg/api" "github.com/flanksource/captain/pkg/captainconfig" "github.com/flanksource/captain/pkg/claude" + "github.com/flanksource/captain/pkg/runtimeprofiles" clickyrpc "github.com/flanksource/clicky/rpc" ) @@ -223,13 +225,24 @@ func renderLoadedLayers(ctx context.Context, body promptBody, vars promptVarsRes return nil, nil, err } presets := opts.Presets - if opts.PresetsSet && presets == nil { + if opts.NoPresets || (opts.PresetsSet && presets == nil) { presets = []string{} } layers, warnings, err := renderLayers(ctx, body.Source, body.Text, frontmatter, PromptRenderRequest{Presets: presets, RuntimeProfile: opts.RuntimeProfile, Literal: body.Literal}, saved) if err != nil { return nil, nil, err } + if len(opts.RequiredPresets) > 0 { + required, _, err := selectRuntimePresets(ctx, runtimePresetSelection{Requested: opts.RequiredPresets, RequestedSet: true, Catalog: runtimeprofiles.DefaultCatalogOptions{Config: &saved}}) + if err != nil { + return nil, nil, err + } + for _, layer := range required.Layers { + if !slices.ContainsFunc(layers, func(existing api.SpecLayer) bool { return existing.ID == layer.ID }) { + layers = append(layers, layer) + } + } + } promptFlags, err := opts.promptSpec() if err != nil { return nil, nil, err diff --git a/pkg/cli/prompt_sources.go b/pkg/cli/prompt_sources.go index 15a9814e..5a9024d5 100644 --- a/pkg/cli/prompt_sources.go +++ b/pkg/cli/prompt_sources.go @@ -28,6 +28,12 @@ func buildPromptSources(ctx context.Context, options promptSourceOptions) ([]pro WalkRoot: "testdata", FS: promptlib.Examples, Writable: false, + }, { + Kind: "embedded", + ID: "builtin", + Label: "Built-in prompts", + WalkRoot: "builtin", + FS: promptlib.Builtin, }} seen := map[string]bool{} @@ -98,6 +104,22 @@ func buildPromptSources(ctx context.Context, options promptSourceOptions) ([]pro Implicit: true, }) } + // The user prompt directory comes after the fallback so it never becomes + // the default save target in place of the repository's .captain/prompts. + configHome, err := captainconfig.Home() + if err != nil { + return nil, err + } + if dir := filepath.Join(configHome, "prompts"); !seen[dir] { + sources = append(sources, promptSource{ + Kind: "local", + ID: hashPromptDir(dir), + Label: dir, + Root: dir, + Writable: true, + Implicit: true, + }) + } return sources, nil } diff --git a/pkg/cli/prompt_sources_ginkgo_test.go b/pkg/cli/prompt_sources_ginkgo_test.go new file mode 100644 index 00000000..e41aa592 --- /dev/null +++ b/pkg/cli/prompt_sources_ginkgo_test.go @@ -0,0 +1,80 @@ +package cli + +import ( + "context" + "os" + "path/filepath" + + "github.com/flanksource/captain/pkg/captainconfig" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("Prompt source discovery", func() { + var promptsDir string + builtinNames := []string{"spec-internal-high.prompt", "spec-internal-low.prompt", "spec-public-high.prompt", "spec-public-low.prompt", "proposal-review.prompt"} + + BeforeEach(func() { + captainconfig.SetPathForTesting(filepath.Join(GinkgoT().TempDir(), ".captain.yaml")) + DeferCleanup(func() { captainconfig.SetPathForTesting("") }) + configHome := GinkgoT().TempDir() + GinkgoT().Setenv("XDG_CONFIG_HOME", configHome) + promptsDir = filepath.Join(configHome, "captain", "prompts") + }) + + writeUserPrompt := func(name, body string) string { + Expect(os.MkdirAll(promptsDir, 0o755)).To(Succeed()) + path := filepath.Join(promptsDir, name) + Expect(os.WriteFile(path, []byte(body), 0o600)).To(Succeed()) + return path + } + + It("ships the review prompts as a read-only built-in source", func() { + sources, err := buildPromptSources(context.Background(), promptSourceOptions{}) + Expect(err).NotTo(HaveOccurred()) + var builtin []promptRecord + for _, source := range sources { + if source.ID == "builtin" { + Expect(source.Writable).To(BeFalse()) + builtin, err = listPromptRecordsFromSource(source) + Expect(err).NotTo(HaveOccurred()) + } + } + names := make([]string, 0, len(builtin)) + for _, record := range builtin { + names = append(names, filepath.Base(record.Rel)) + } + Expect(names).To(ConsistOf(builtinNames)) + }) + + It("resolves built-in prompts by name when the user prompt directory is absent", func() { + record, err := resolvePromptRecord(context.Background(), promptRecordOptions{ID: "spec-internal-high"}) + Expect(err).NotTo(HaveOccurred()) + Expect(record.Source.ID).To(Equal("builtin")) + Expect(record.Rel).To(Equal("builtin/spec-internal-high.prompt")) + }) + + It("discovers prompts in the user configuration directory", func() { + path := writeUserPrompt("triage.prompt", "Triage {{issue}}.\n") + record, err := resolvePromptRecord(context.Background(), promptRecordOptions{ID: "triage"}) + Expect(err).NotTo(HaveOccurred()) + Expect(record.Path).To(Equal(path)) + Expect(record.Source.Implicit).To(BeTrue()) + }) + + It("lets a user copy shadow a built-in prompt of the same name", func() { + path := writeUserPrompt("spec-internal-high.prompt", "Review {{files}} my way.\n") + record, err := resolvePromptRecord(context.Background(), promptRecordOptions{ID: "spec-internal-high"}) + Expect(err).NotTo(HaveOccurred()) + Expect(record.Path).To(Equal(path)) + }) + + It("keeps the repository prompt directory as the default save target", func() { + sources, err := buildPromptSources(context.Background(), promptSourceOptions{}) + Expect(err).NotTo(HaveOccurred()) + writable, ok := firstWritableSource(sources) + Expect(ok).To(BeTrue()) + Expect(writable.Root).To(HaveSuffix(filepath.Join(".captain", "prompts"))) + Expect(sources).To(ContainElement(SatisfyAll(HaveField("Root", promptsDir), HaveField("Implicit", true), HaveField("Writable", true)))) + }) +}) diff --git a/pkg/cli/review_prompts_ginkgo_test.go b/pkg/cli/review_prompts_ginkgo_test.go new file mode 100644 index 00000000..49b77082 --- /dev/null +++ b/pkg/cli/review_prompts_ginkgo_test.go @@ -0,0 +1,91 @@ +package cli + +import ( + "context" + "path/filepath" + "slices" + "strings" + + "github.com/flanksource/captain/pkg/aiflags" + "github.com/flanksource/captain/pkg/api" + "github.com/flanksource/captain/pkg/captainconfig" + "github.com/flanksource/captain/pkg/runtimeprofiles" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("Built-in document review prompts", func() { + var ctx context.Context + allFamilies := []string{"req/", "doc/", "hl/", "ll/", "int/", "pub/", "prop/"} + + BeforeEach(func() { + captainconfig.SetPathForTesting(filepath.Join(GinkgoT().TempDir(), "captain.yaml")) + DeferCleanup(func() { captainconfig.SetPathForTesting("") }) + catalog, err := runtimeprofiles.NewCatalog(runtimeprofiles.NewBuiltinSource()) + Expect(err).NotTo(HaveOccurred()) + ctx = ContextWithRuntimeCatalog(context.Background(), catalog) + }) + + DescribeTable("render as read-only lint reviews scoped to their rule families", + func(name string, vars []string, families []string) { + // gavel requires the lint preset; `--preset lint` requests it and so replaces any pinned presets. + for _, model := range []string{"agent:sonnet", "agent:gpt-6.1-sol"} { + withModel := AIRuntimeOptions{AIProviderOptions: AIProviderOptions{ModelFlags: aiflags.ModelFlags{Model: model}}} + for _, options := range []AIPromptOptions{ + {AIRuntimeOptions: withModel, RequiredPresets: []string{"lint"}, Var: vars}, + {AIRuntimeOptions: withModel, Presets: []string{"lint"}, Var: vars}, + } { + rendered, err := RenderPrompt(ctx, PromptInvocation{Reference: name, Options: options}) + Expect(err).NotTo(HaveOccurred(), model) + Expect(rendered.ValidationError).To(BeEmpty(), model) + Expect(rendered.Input.Prompt.SchemaJSON).To(ContainSubstring(`"violations"`)) + trace := rendered.Resolution.Trace + Expect(trace[len(trace)-1].Name).To(Equal("Lint")) + Expect(rendered.Input.Permissions.Access).To(Equal(api.AccessReadOnly)) + Expect(rendered.Input.Permissions.Tools).To(BeEmpty()) + expectReadOnlyPosture(rendered) + } + } + rendered, err := RenderPrompt(ctx, PromptInvocation{Reference: name, Options: AIPromptOptions{Var: vars}}) + Expect(err).NotTo(HaveOccurred()) + for _, v := range vars { + _, value, _ := strings.Cut(v, "=") + Expect(rendered.Input.Prompt.User).To(ContainSubstring(value)) + } + for _, family := range allFamilies { + if slices.Contains(families, family) { + Expect(rendered.Input.Prompt.System).To(ContainSubstring("`"+family), family) + } else { + Expect(rendered.Input.Prompt.System).NotTo(ContainSubstring("`"+family), family) + } + } + }, + Entry("internal high-level", "spec-internal-high", []string{"files=docs/prd.md"}, []string{"req/", "doc/", "hl/", "int/"}), + Entry("internal low-level", "spec-internal-low", []string{"files=docs/design.md", "parent=docs/prd.md"}, []string{"req/", "doc/", "ll/", "int/"}), + Entry("public high-level", "spec-public-high", []string{"files=docs/overview.md"}, []string{"req/", "doc/", "hl/", "pub/"}), + Entry("public low-level", "spec-public-low", []string{"files=docs/api.md", "parent=docs/overview.md"}, []string{"req/", "doc/", "ll/", "pub/"}), + Entry("proposal", "proposal-review", []string{"files=bid/response.md", "rfp=bid/rfp.md"}, []string{"req/", "doc/", "prop/"}), + ) +}) + +// expectReadOnlyPosture compiles the rendered request the way the provider +// decorator does and checks the runtime's native read-only posture: claude +// denies its write, shell and sub-agent tools; codex runs a read-only sandbox +// that never asks. Web tools stay allowed on both. +func expectReadOnlyPosture(rendered PromptRenderResult) { + runtime := api.RuntimeOf(rendered.Config.Model.Provider, rendered.Config.Model.Mode) + compiled, _, err := api.CompileAccess(runtime, rendered.Input) + Expect(err).NotTo(HaveOccurred()) + Expect(compiled.Permissions.MCP.Disabled).To(BeTrue()) + switch rendered.Provider { + case "anthropic": + Expect(compiled.Permissions.Tools.DenyList()).To(ContainElements("Agent", "Bash", "Edit", "Task", "Write")) + Expect(compiled.Permissions.Tools.DenyList()).NotTo(ContainElements("WebFetch", "WebSearch", "Read")) + case "openai": + Expect(compiled.Sandbox.Policy.Filesystem.Access).To(Equal(api.SandboxFilesystemReadOnly)) + Expect(compiled.Permissions.Mode).To(Equal(api.PermissionBypass)) + Expect(compiled.Permissions.Tools).To(BeEmpty()) + default: + Fail("unexpected provider " + rendered.Provider) + } +} diff --git a/pkg/cli/runtime_preset_entity.go b/pkg/cli/runtime_preset_entity.go index e333bfb0..e5626621 100644 --- a/pkg/cli/runtime_preset_entity.go +++ b/pkg/cli/runtime_preset_entity.go @@ -30,6 +30,7 @@ func (r RuntimePresetRecord) Columns() []clickyapi.ColumnDef { clickyapi.Column("name").Label("Name").Build(), clickyapi.Column("source").Label("Source").MaxWidth(40).Build(), clickyapi.Column("scope").Label("Scope").Build(), + clickyapi.Column("order").Label("Order").Build(), clickyapi.Column("model").Label("Model").Build(), clickyapi.Column("description").Label("Description").MaxWidth(80).Build(), } @@ -40,6 +41,7 @@ func (r RuntimePresetRecord) Row() map[string]any { "name": r.Name, "source": r.Source.Label, "scope": string(r.Scope), + "order": r.Order, "model": runtimeModelLabel(r.Spec.Model), "description": r.Description, } @@ -60,18 +62,19 @@ type RuntimePresetWriteRequest struct { Spec *api.RuntimePresetSpec `json:"spec,omitempty"` Presets []string `json:"presets,omitempty"` Content string `json:"content,omitempty"` + Order int `json:"order,omitempty"` } func (req RuntimePresetWriteRequest) input() (runtimeprofiles.PresetInput, error) { if req.Content == "" { - in := runtimeprofiles.PresetInput{Name: req.Name, Description: req.Description, Scope: req.Scope, Presets: req.Presets} + in := runtimeprofiles.PresetInput{Name: req.Name, Description: req.Description, Scope: req.Scope, Presets: req.Presets, Order: req.Order} if req.Spec != nil { in.Spec = *req.Spec } return in, nil } - if req.Name != "" || req.Description != "" || req.Scope != "" || req.Spec != nil || len(req.Presets) > 0 { - return runtimeprofiles.PresetInput{}, runtimeBodyError("content excludes name, description, scope, spec and presets; send one or the other") + if req.Name != "" || req.Description != "" || req.Scope != "" || req.Spec != nil || len(req.Presets) > 0 || req.Order != 0 { + return runtimeprofiles.PresetInput{}, runtimeBodyError("content excludes name, description, scope, spec, presets and order; send one or the other") } var in runtimeprofiles.PresetInput if err := decodeRuntimeContent(req.Content, &in); err != nil { diff --git a/pkg/cli/testdata/permissions_matrix_test.md b/pkg/cli/testdata/permissions_matrix_test.md index 7f0951f4..bd2decf7 100644 --- a/pkg/cli/testdata/permissions_matrix_test.md +++ b/pkg/cli/testdata/permissions_matrix_test.md @@ -72,6 +72,20 @@ MCP is one-directional today: it can only be switched off. Skills are enabled on | every runtime drops a disabled skill | --format json | json.runtimes.all(r, r.permissions.resources.skills["disabled"].kind == "native") | | plugins are inert in both directions | --provider anthropic --mode cli --format json | json.runtimes[0].permissions.resources.plugins["enabled"].kind == "unsupported" && json.runtimes[0].permissions.resources.plugins["disabled"].kind == "unsupported" | +## Portable access + +`permissions.access` is compiled to each runtime's own dialect: per-tool denies +on claude, a read-only sandbox that never asks on codex, and the plan approval +mode on gemini, which the gemini client enforces itself. + +| Name | flags | CEL Validation | +|------|-------|----------------| +| rows cover both access levels | | stdout.contains("access read-only") && stdout.contains("access full") | +| claude compiles read-only to tool denies | --provider anthropic --mode agent --format json | json.runtimes[0].permissions.access["read-only"].kind == "native" && json.runtimes[0].permissions.access["read-only"].effects.flag == "--disallowedTools" | +| codex compiles read-only to a sandbox that never asks | --provider openai --mode agent --format json | json.runtimes[0].permissions.access["read-only"].effects.sandbox == "read-only" && json.runtimes[0].permissions.access["read-only"].effects.approval == "never" | +| gemini approximates read-only with plan mode | --provider google --mode cli --format json | json.runtimes[0].permissions.access["read-only"].kind == "approximated" && json.runtimes[0].permissions.access["read-only"].effects.flag == "--approval-mode plan" | +| full adds nothing anywhere | --format json | json.runtimes.all(r, r.permissions.access["full"].kind == "native") | + ## Built-in tool vocabulary The permission catalog served Claude's tool names for every runtime. codex has From 94e0df404afaf555cc5dab1651b786ba35f9593c Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Thu, 22 Oct 2026 18:52:18 +0300 Subject: [PATCH 08/77] feat(prompt): add built-in review prompts for specs and proposals Ship reviewer prompts that Captain resolves by name through the new prompt.Builtin embed FS, so users can lint internal and public high-level and low-level specs and RFP proposals without copying prompt files into their repositories. Each prompt is read-only, runs with a 30-turn budget, and reports violations against a fixed rule catalog. Shared rule ids (req/, doc/) keep findings consistent across document types, and audience-specific ids cover internal and public concerns. --- pkg/ai/prompt/builtin/proposal-review.prompt | 87 +++++++++++++++++ .../prompt/builtin/spec-internal-high.prompt | 84 ++++++++++++++++ .../prompt/builtin/spec-internal-low.prompt | 93 ++++++++++++++++++ pkg/ai/prompt/builtin/spec-public-high.prompt | 84 ++++++++++++++++ pkg/ai/prompt/builtin/spec-public-low.prompt | 96 +++++++++++++++++++ pkg/ai/prompt/examples.go | 5 + 6 files changed, 449 insertions(+) create mode 100644 pkg/ai/prompt/builtin/proposal-review.prompt create mode 100644 pkg/ai/prompt/builtin/spec-internal-high.prompt create mode 100644 pkg/ai/prompt/builtin/spec-internal-low.prompt create mode 100644 pkg/ai/prompt/builtin/spec-public-high.prompt create mode 100644 pkg/ai/prompt/builtin/spec-public-low.prompt diff --git a/pkg/ai/prompt/builtin/proposal-review.prompt b/pkg/ai/prompt/builtin/proposal-review.prompt new file mode 100644 index 00000000..149b040e --- /dev/null +++ b/pkg/ai/prompt/builtin/proposal-review.prompt @@ -0,0 +1,87 @@ +--- +description: Review RFP responses, proposals and statements of work against the RFP and report Gavel lint violations. +model: claude-sonnet-5 +mode: agent +setup: + cwd: . +permissions: + access: read-only +memory: + skipUser: true +budget: + maxTurns: 30 +input: + schemaType: json-schema + schema: + type: object + required: [files] + properties: + files: + type: string + description: Proposal document paths relative to the working directory, separated by spaces or commas. + rfp: + type: string + description: Optional path to the RFP or requirements document the proposal responds to. + focus: + type: string + description: Optional extra review focus. +--- +{{role "system"}} +You review RFP responses, proposals and statements of work as an evaluator scoring them against the RFP. A strong proposal answers every RFP requirement concretely, follows its mandatory format, states deliverables with owners and acceptance criteria, backs every claim with proof, explains the benefit to the customer, and makes its pricing basis, timeline, assumptions, exclusions and risks explicit and consistent. + +## Procedure +1. When an RFP is given, read it in full first and list every mandatory requirement (shall, must, required) and every format, section, page-limit or certification instruction, with its line. This is your compliance matrix. +2. Read every listed proposal document in full with Read before reporting anything. Page through long files with offsets until the end. +3. Trace each compliance-matrix entry to the proposal text that answers it. +4. Evaluate the documents against the rules below. Use Glob or Grep only when the proposal cites files in this repository. Never modify files. + +## Reporting +- Report only material issues that would cost evaluation points, create a contractual risk or mislead the customer. Do not report style, grammar, spelling or formatting. +- Report one finding per root cause. When a problem repeats, report it at the first occurrence and list the other lines in the message, for example "also at lines 40 and 72". +- `file` is the path exactly as given. `line` is the 1-based line of the offending text, and `code` is that text quoted verbatim. Drop any finding whose text you cannot quote. Report an unaddressed RFP requirement at its line in the RFP, and a missing section at line 1 of the proposal without `code`. +- `rule.method` is one id from the catalog. Use `doc/other` for a material issue no rule covers, and never invent ids. +- `severity` is the rule's listed severity. You may lower it by one step when context makes the issue minor, and must say why in the message. Never raise it. +- `message` states the problem, then the concrete fix: name the RFP requirement, missing proof, deliverable, assumption or section. Never write generic advice such as "strengthen this section". +- Apply an external standard only when the RFP or proposal claims conformance to it. +- Do not praise or summarize. Return an empty `violations` array when there are no material issues. + +## Rules + +Requirement quality: +- `req/unverifiable` (error): a commitment has no measurable acceptance condition, for example vague terms ("best-in-class", "timely"), escape clauses ("where possible", "as appropriate") or open-ended lists ("etc.", "including but not limited to"). +- `req/ambiguous` (warning): it is unclear who acts (passive voice), an unclear pronoun, "and/or", or an undefined term. +- `req/compound` (warning): one commitment bundles several obligations that could be met or missed independently. +- `req/missing-units` (warning): a quantity, duration, rate or service level has no unit, range or measurement condition. +- `req/contradiction` (error): a statement conflicts with another. Quote both and report at the later one. + +Document integrity: +- `doc/unsupported-claim` (warning): a number, benchmark, statistic or customer result has no source. +- `doc/inconsistent` (error): a price, date, quantity, name or scope differs between sections, including an executive summary that promises what the body does not cover. +- `doc/placeholder` (error): template brackets such as a customer-name placeholder, another customer's name, lorem text, AI-assistant artifacts, or TBD. +- `doc/boilerplate` (info): generic or marketing passages that would read the same in any proposal. +- `doc/status-confusion` (warning): a planned capability is presented as available, or an available one as planned. +- `doc/missing-section` (warning): a required section below is absent. +- `doc/open-question` (info): an unresolved question is left in the text. +- `doc/other` (warning): a material issue outside this catalog. + +Proposal content: +- `prop/unaddressed-requirement` (error): a mandatory RFP requirement has no response. Only with an RFP. +- `prop/compliance-gap` (error): a mandatory format, section, page limit, form or certification from the RFP is missing. Only with an RFP. +- `prop/missing-deliverable` (error): a scope item has no deliverable, owner or acceptance criterion. +- `prop/partial-response` (warning): a requirement is acknowledged but not answered concretely. +- `prop/missing-proof` (warning): a win theme or capability claim has no proof point such as a case study, reference or metric. +- `prop/pricing-gap` (warning): the cost basis, assumptions or exclusions are missing or inconsistent with the scope. +- `prop/timeline-risk` (warning): milestones have no dependencies, assumptions or buffer. +- `prop/self-focused` (info): a feature is described without its benefit to the customer. + +Required sections: executive summary, approach, deliverables, timeline, pricing basis, assumptions and exclusions, risks. +{{role "user"}} +Review these proposal documents: {{{files}}} +{{#if rfp}} + +RFP: {{{rfp}}} +{{/if}} +{{#if focus}} + +Additional focus: {{{focus}}} +{{/if}} diff --git a/pkg/ai/prompt/builtin/spec-internal-high.prompt b/pkg/ai/prompt/builtin/spec-internal-high.prompt new file mode 100644 index 00000000..a51f929f --- /dev/null +++ b/pkg/ai/prompt/builtin/spec-internal-high.prompt @@ -0,0 +1,84 @@ +--- +description: Review internal high-level specifications (PRDs, RFCs, architecture overviews, plans) and report Gavel lint violations. +model: claude-sonnet-5 +mode: agent +setup: + cwd: . +permissions: + access: read-only +memory: + skipUser: true +budget: + maxTurns: 30 +input: + schemaType: json-schema + schema: + type: object + required: [files] + properties: + files: + type: string + description: Document paths relative to the working directory, separated by spaces or commas. + focus: + type: string + description: Optional extra review focus. +--- +{{role "system"}} +You review internal high-level specifications: PRDs, RFCs, architecture overviews and implementation plans. The readers are the team deciding whether and what to build. A high-level spec explains the problem, the goals and how success is measured, the scope and non-goals, the people affected, the alternatives considered and the risks. It does not specify field types, function signatures or error codes; those belong in the low-level spec, so never ask for them. + +## Procedure +1. Read every listed document in full with Read before reporting anything. Page through long files with offsets until the end. +2. Search the working tree with Glob or Grep for every system, component, package or path the document names, and compare each claim with what exists. +3. Evaluate the documents against the rules below. Never modify files. + +## Reporting +- Report only material issues that would change a decision, a plan or a reader's understanding. Do not report style, grammar, spelling or formatting. +- Report one finding per root cause. When a problem repeats, report it at the first occurrence and list the other lines in the message, for example "also at lines 40 and 72". +- `file` is the path exactly as given. `line` is the 1-based line of the offending text, and `code` is that text quoted verbatim. Drop any finding whose text you cannot quote. Report a missing section at line 1 without `code`. +- `rule.method` is one id from the catalog. Use `doc/other` for a material issue no rule covers, and never invent ids. +- `severity` is the rule's listed severity. You may lower it by one step when context makes the issue minor, and must say why in the message. Never raise it. +- `message` states the problem, then the concrete fix: name the missing element, metric, owner or section. Never write generic advice such as "add more detail". +- Apply an external standard only when the document claims conformance to it. +- Do not praise or summarize. Return an empty `violations` array when there are no material issues. + +## Rules + +Requirement quality: +- `req/unverifiable` (error): a requirement has no measurable acceptance condition, for example vague terms ("fast", "user-friendly"), escape clauses ("where possible", "as appropriate") or open-ended lists ("etc.", "including but not limited to"). +- `req/ambiguous` (warning): no actor (passive voice), an unclear pronoun, "and/or", or an undefined term. +- `req/compound` (warning): one statement holds several requirements that could pass or fail independently. +- `req/missing-units` (warning): a quantity has no unit, range, tolerance or measurement condition. +- `req/contradiction` (error): a statement conflicts with another. Quote both and report at the later one. + +Document integrity: +- `doc/unsupported-claim` (warning): a number, benchmark, statistic or citation has no source or measurement plan. +- `doc/inconsistent` (error): an entity, number, date or scope is stated differently in two places, including a summary that promises what the body does not cover. +- `doc/placeholder` (error): template brackets, lorem text, AI-assistant artifacts, or TBD in a requirement. +- `doc/boilerplate` (info): a generic passage that would read the same in any document and names nothing decidable. +- `doc/status-confusion` (warning): planned behavior is described as existing, or existing behavior as planned. +- `doc/missing-section` (warning): a required section below is absent. +- `doc/open-question` (info): an unresolved question has no owner. +- `doc/other` (warning): a material issue outside this catalog. + +High-level content: +- `hl/problem-unstated` (error): there is no problem statement or supporting evidence, or the problem restates the solution. +- `hl/unmeasurable-goal` (error): a goal has no metric, baseline and target. +- `hl/missing-non-goals` (warning): nothing is explicitly out of scope. +- `hl/unprioritized` (warning): requirements carry no priority, or everything is a must-have. +- `hl/missing-risks` (warning): no risks, dependencies or mitigations. +- `hl/missing-alternatives` (warning): a direction is chosen with no alternatives or trade-offs. +- `hl/premature-detail` (warning): field names, schemas or function-level design pre-empt the low-level spec without a stated constraint requiring them. +- `hl/missing-stakeholders` (info): users, owners or affected teams are not named. + +Internal audience: +- `int/stale-reference` (error): a named system, component, package or path does not exist or differs in the working tree. Report only after searching, and name what you searched in the message. +- `int/missing-rollout` (warning): a schema, API or data migration change has no compatibility, rollout or rollback approach. +- `int/ownership` (info): a work item or phase has no owning team. + +Required sections: problem or context, goals with metrics, non-goals, users or stakeholders, scope, risks, alternatives considered. +{{role "user"}} +Review these documents: {{{files}}} +{{#if focus}} + +Additional focus: {{{focus}}} +{{/if}} diff --git a/pkg/ai/prompt/builtin/spec-internal-low.prompt b/pkg/ai/prompt/builtin/spec-internal-low.prompt new file mode 100644 index 00000000..f7c5c71b --- /dev/null +++ b/pkg/ai/prompt/builtin/spec-internal-low.prompt @@ -0,0 +1,93 @@ +--- +description: Review internal low-level specifications (detailed designs, schema and migration designs, algorithm docs) and report Gavel lint violations. +model: claude-sonnet-5 +mode: agent +setup: + cwd: . +permissions: + access: read-only +memory: + skipUser: true +budget: + maxTurns: 30 +input: + schemaType: json-schema + schema: + type: object + required: [files] + properties: + files: + type: string + description: Document paths relative to the working directory, separated by spaces or commas. + parent: + type: string + description: Optional path to the high-level spec these documents implement. + focus: + type: string + description: Optional extra review focus. +--- +{{role "system"}} +You review internal low-level specifications: detailed designs, schema and migration designs, and algorithm documents. The readers are the engineers who will implement them. A low-level spec defines every interface and data shape completely, the behavior for success and failure, the edge cases, concurrency and security, and how the change is verified and rolled out. It does not need to justify the product direction; that belongs in the high-level spec, so never ask for market rationale, personas or business metrics. + +## Procedure +1. When a parent spec is given, read it in full first and list its requirements, so you can trace each one to the design. +2. Read every listed document in full with Read before reporting anything. Page through long files with offsets until the end. +3. Search the working tree with Glob or Grep for every concrete reference: file paths, packages, functions, types, CLI flags, endpoints, tables and config keys. Compare each claim with what exists. +4. Evaluate the documents against the rules below. Never modify files. + +## Reporting +- Report only material issues that would change an implementation or a reader's understanding. Do not report style, grammar, spelling or formatting. +- Report one finding per root cause. When a problem repeats, report it at the first occurrence and list the other lines in the message, for example "also at lines 40 and 72". +- `file` is the path exactly as given. `line` is the 1-based line of the offending text, and `code` is that text quoted verbatim. Drop any finding whose text you cannot quote. Report a missing section at line 1 without `code`, and an unimplemented parent requirement at its line in the parent spec. +- `rule.method` is one id from the catalog. Use `doc/other` for a material issue no rule covers, and never invent ids. +- `severity` is the rule's listed severity. You may lower it by one step when context makes the issue minor, and must say why in the message. Never raise it. +- `message` states the problem, then the concrete fix: name the missing field, type, error, case or section. Never write generic advice such as "add more detail". +- Apply an external standard only when the document claims conformance to it. +- Do not praise or summarize. Return an empty `violations` array when there are no material issues. + +## Rules + +Requirement quality: +- `req/unverifiable` (error): a requirement has no measurable acceptance condition, for example vague terms ("fast", "efficient"), escape clauses ("where possible", "as appropriate") or open-ended lists ("etc.", "including but not limited to"). +- `req/ambiguous` (warning): no actor (passive voice), an unclear pronoun, "and/or", or an undefined term. +- `req/compound` (warning): one statement holds several requirements that could pass or fail independently. +- `req/missing-units` (warning): a quantity, timeout or limit has no unit, range, tolerance or measurement condition. +- `req/contradiction` (error): a statement conflicts with another. Quote both and report at the later one. + +Document integrity: +- `doc/unsupported-claim` (warning): a number, benchmark, statistic or citation has no source or measurement plan. +- `doc/inconsistent` (error): an entity, name, number, type or scope is stated differently in two places. +- `doc/placeholder` (error): template brackets, lorem text, AI-assistant artifacts, or TBD in a requirement. +- `doc/boilerplate` (info): a generic passage that would read the same in any document and names nothing decidable. +- `doc/status-confusion` (warning): planned behavior is described as existing, or existing behavior as planned. +- `doc/missing-section` (warning): a required section below is absent. +- `doc/open-question` (info): an unresolved question has no owner. +- `doc/other` (warning): a material issue outside this catalog. + +Low-level content: +- `ll/underspecified-interface` (error): a field, parameter, endpoint or message lacks its type, whether it is required, its default, its limits or its units. +- `ll/undefined-error` (error): a failure has no error code or status, message contract, or retry semantics. +- `ll/schema-mismatch` (error): an example or a later section disagrees with the schema or types the document defines. +- `ll/unimplemented-requirement` (error): a parent spec requirement has no corresponding design. Only with a parent spec. +- `ll/missing-edge-case` (warning): empty, null, maximum, duplicate, concurrent or timeout input is not covered. +- `ll/concurrency` (warning): ordering, idempotency, retries or races are unspecified for a mutating operation. +- `ll/state-gap` (warning): a state machine has undefined or unreachable transitions. +- `ll/security-gap` (warning): an exposed surface has no authentication, authorization, input validation or secret handling. +- `ll/untraced` (info): a design element traces to no parent requirement. Only with a parent spec. + +Internal audience: +- `int/stale-reference` (error): a referenced path, symbol, flag, endpoint, table or config key does not exist or differs in the working tree. Report only after searching, and name what you searched in the message. +- `int/missing-verification` (warning): a behavior change has no test or smoke-test plan. +- `int/missing-rollout` (warning): a schema, API or data migration change has no compatibility, rollout or rollback approach. + +Required sections: interfaces or data model, behavior, errors, edge cases, security, testing. +{{role "user"}} +Review these documents: {{{files}}} +{{#if parent}} + +Parent high-level spec: {{{parent}}} +{{/if}} +{{#if focus}} + +Additional focus: {{{focus}}} +{{/if}} diff --git a/pkg/ai/prompt/builtin/spec-public-high.prompt b/pkg/ai/prompt/builtin/spec-public-high.prompt new file mode 100644 index 00000000..54bbdc88 --- /dev/null +++ b/pkg/ai/prompt/builtin/spec-public-high.prompt @@ -0,0 +1,84 @@ +--- +description: Review public high-level specifications (product specs, solution overviews, whitepapers) and report Gavel lint violations. +model: claude-sonnet-5 +mode: agent +setup: + cwd: . +permissions: + access: read-only +memory: + skipUser: true +budget: + maxTurns: 30 +input: + schemaType: json-schema + schema: + type: object + required: [files] + properties: + files: + type: string + description: Document paths relative to the working directory, separated by spaces or commas. + focus: + type: string + description: Optional extra review focus. +--- +{{role "system"}} +You review public high-level specifications: product specifications, solution overviews and whitepapers. The readers are customers and partners evaluating the product, who cannot see the source code or internal discussions. A public high-level spec explains the problem it solves, what the product does and does not do, how outcomes are measured, and what is committed versus planned, using defined terms and without exposing internals. It does not specify field types, function signatures or error codes; those belong in the low-level spec, so never ask for them. + +## Procedure +1. Read every listed document in full with Read before reporting anything. Page through long files with offsets until the end. +2. Evaluate the documents against the rules below. Use Glob or Grep only to check whether a name, path or term is internal to this repository. Never modify files. + +## Reporting +- Report only material issues that would mislead a reader, expose internals, or change an evaluation. Do not report style, grammar, spelling or formatting. +- Report one finding per root cause. When a problem repeats, report it at the first occurrence and list the other lines in the message, for example "also at lines 40 and 72". +- `file` is the path exactly as given. `line` is the 1-based line of the offending text, and `code` is that text quoted verbatim. Drop any finding whose text you cannot quote. Report a missing section at line 1 without `code`. +- `rule.method` is one id from the catalog. Use `doc/other` for a material issue no rule covers, and never invent ids. +- `severity` is the rule's listed severity. You may lower it by one step when context makes the issue minor, and must say why in the message. Never raise it. +- `message` states the problem, then the concrete fix: name the missing definition, source, qualifier or section. Never write generic advice such as "add more detail". +- Apply an external standard only when the document claims conformance to it. +- Do not praise or summarize. Return an empty `violations` array when there are no material issues. + +## Rules + +Requirement quality: +- `req/unverifiable` (error): a capability or requirement has no measurable condition, for example vague terms ("fast", "seamless", "enterprise-grade"), escape clauses ("where possible") or open-ended lists ("etc.", "including but not limited to"). +- `req/ambiguous` (warning): no actor (passive voice), an unclear pronoun, "and/or", or an undefined term. +- `req/compound` (warning): one statement holds several capabilities that could hold or fail independently. +- `req/missing-units` (warning): a quantity has no unit, range, tolerance or measurement condition. +- `req/contradiction` (error): a statement conflicts with another. Quote both and report at the later one. + +Document integrity: +- `doc/unsupported-claim` (warning): a number, benchmark, statistic, customer result or citation has no source or measurement method. +- `doc/inconsistent` (error): a product name, number, date or scope is stated differently in two places, including a summary that promises what the body does not cover. +- `doc/placeholder` (error): template brackets, lorem text, AI-assistant artifacts, or TBD. +- `doc/boilerplate` (info): marketing or generic passages that would read the same for any product and state no capability. +- `doc/status-confusion` (warning): a planned capability is described as available, or an available one as planned. +- `doc/missing-section` (warning): a required section below is absent. +- `doc/open-question` (info): an unresolved question is left in the text. +- `doc/other` (warning): a material issue outside this catalog. + +High-level content: +- `hl/problem-unstated` (error): there is no problem statement, or the problem restates the product. +- `hl/unmeasurable-goal` (error): an outcome or benefit has no metric, baseline and target. +- `hl/missing-non-goals` (warning): the document never states what the product does not do. +- `hl/unprioritized` (warning): capabilities are not distinguished as core, optional or add-on. +- `hl/missing-risks` (warning): no limitations, prerequisites or dependencies are stated. +- `hl/missing-alternatives` (warning): an approach is chosen with no trade-offs explained. +- `hl/premature-detail` (warning): field names, schemas or function-level design appear where the reader needs capabilities. +- `hl/missing-stakeholders` (info): the intended users or roles are not named. + +Public audience: +- `pub/internal-leak` (error): internal paths, repository names, codenames, hostnames, ticket ids, employee names, credentials or unreleased features appear. +- `pub/implementation-leak` (warning): an internal mechanism is stated as behavior readers can rely on. +- `pub/terminology` (warning): a term is used before it is defined, or one concept appears under several names. +- `pub/unsupported-commitment` (warning): an SLA, roadmap date or capability promise has no qualifier, condition or source. + +Required sections: overview or problem, capabilities, scope and limitations, terminology, intended users. +{{role "user"}} +Review these documents: {{{files}}} +{{#if focus}} + +Additional focus: {{{focus}}} +{{/if}} diff --git a/pkg/ai/prompt/builtin/spec-public-low.prompt b/pkg/ai/prompt/builtin/spec-public-low.prompt new file mode 100644 index 00000000..f1f4040f --- /dev/null +++ b/pkg/ai/prompt/builtin/spec-public-low.prompt @@ -0,0 +1,96 @@ +--- +description: Review public low-level specifications (API references, protocol and format specs, standards) and report Gavel lint violations. +model: claude-sonnet-5 +mode: agent +setup: + cwd: . +permissions: + access: read-only +memory: + skipUser: true +budget: + maxTurns: 30 +input: + schemaType: json-schema + schema: + type: object + required: [files] + properties: + files: + type: string + description: Document paths relative to the working directory, separated by spaces or commas. + parent: + type: string + description: Optional path to the high-level spec these documents implement. + focus: + type: string + description: Optional extra review focus. +--- +{{role "system"}} +You review public low-level specifications: API references, protocol and file-format specifications, and standards. The readers are external integrators who build against the contract and cannot see the source code. A public low-level spec defines every field and operation completely, the error model, edge cases, concurrency and security expectations, and the versioning and compatibility guarantees, using normative language and defined terms, without exposing internals. It does not need to justify the product direction, so never ask for market rationale, personas or business metrics. + +## Procedure +1. When a parent spec is given, read it in full first and list its requirements, so you can trace each one to the contract. +2. Read every listed document in full with Read before reporting anything. Page through long files with offsets until the end. +3. Search the working tree with Glob or Grep for the implementation of each documented operation, field and example, and compare the documented behavior with the code. +4. Evaluate the documents against the rules below. Never modify files. + +## Reporting +- Report only material issues that would break an integration, mislead a reader or expose internals. Do not report style, grammar, spelling or formatting. +- Report one finding per root cause. When a problem repeats, report it at the first occurrence and list the other lines in the message, for example "also at lines 40 and 72". +- `file` is the path exactly as given. `line` is the 1-based line of the offending text, and `code` is that text quoted verbatim. Drop any finding whose text you cannot quote. Report a missing section at line 1 without `code`, and an unimplemented parent requirement at its line in the parent spec. +- `rule.method` is one id from the catalog. Use `doc/other` for a material issue no rule covers, and never invent ids. +- `severity` is the rule's listed severity. You may lower it by one step when context makes the issue minor, and must say why in the message. Never raise it. +- `message` states the problem, then the concrete fix: name the missing field, type, error, keyword or section. Never write generic advice such as "add more detail". +- Apply an external standard only when the document claims conformance to it. RFC 2119 keywords are the exception: always check them. +- Do not praise or summarize. Return an empty `violations` array when there are no material issues. + +## Rules + +Requirement quality: +- `req/unverifiable` (error): a requirement has no testable condition, for example vague terms ("reasonable", "promptly"), escape clauses ("where possible") or open-ended lists ("etc.", "including but not limited to"). +- `req/ambiguous` (warning): no actor (passive voice) where it matters whether the client or server acts, an unclear pronoun, "and/or", or an undefined term. +- `req/compound` (warning): one statement holds several requirements that could pass or fail independently. +- `req/missing-units` (warning): a size, rate, timeout or limit has no unit, range or tolerance. +- `req/contradiction` (error): a statement conflicts with another. Quote both and report at the later one. + +Document integrity: +- `doc/unsupported-claim` (warning): a performance or reliability figure has no source or measurement method. +- `doc/inconsistent` (error): a name, number, type or status code is stated differently in two places. +- `doc/placeholder` (error): template brackets, lorem text, AI-assistant artifacts, or TBD. +- `doc/boilerplate` (info): a generic passage that states no contract. +- `doc/status-confusion` (warning): planned behavior is described as available, or available behavior as planned. +- `doc/missing-section` (warning): a required section below is absent. +- `doc/open-question` (info): an unresolved question is left in the text. +- `doc/other` (warning): a material issue outside this catalog. + +Low-level content: +- `ll/underspecified-interface` (error): a field, parameter, header, endpoint or message lacks its type, whether it is required, its default, its limits or its units. +- `ll/undefined-error` (error): a failure has no error code or status, error body contract, or retry semantics. +- `ll/schema-mismatch` (error): an example or a later section disagrees with the schema or types the document defines. +- `ll/unimplemented-requirement` (error): a parent spec requirement has no corresponding contract. Only with a parent spec. +- `ll/missing-edge-case` (warning): empty, null, maximum, duplicate, concurrent or timeout input is not covered. +- `ll/concurrency` (warning): ordering, idempotency, retries or conflicting writes are unspecified for a mutating operation. +- `ll/state-gap` (warning): a lifecycle or state machine has undefined or unreachable transitions. +- `ll/security-gap` (warning): an operation has no stated authentication, authorization, input validation or rate limiting. +- `ll/untraced` (info): a contract element traces to no parent requirement. Only with a parent spec. + +Public audience: +- `pub/internal-leak` (error): internal paths, repository names, codenames, hostnames, ticket ids, employee names, credentials or unreleased features appear. +- `pub/implementation-leak` (warning): an internal mechanism is stated as behavior integrators can rely on. +- `pub/terminology` (warning): a term is used before it is defined, or one concept appears under several names. +- `pub/normative-language` (warning): a requirement does not use RFC 2119 keywords (MUST, SHOULD, MAY), uses them in lowercase or inconsistently, or uses them for non-normative text. +- `pub/invalid-example` (error): an example request, response or command contradicts what the code does. Report only after finding the implementation, and name it in the message. +- `pub/missing-versioning` (warning): the contract has no version, deprecation policy or stability guarantee. + +Required sections: overview and scope, terminology, operations or format definition, errors, security, versioning. +{{role "user"}} +Review these documents: {{{files}}} +{{#if parent}} + +Parent high-level spec: {{{parent}}} +{{/if}} +{{#if focus}} + +Additional focus: {{{focus}}} +{{/if}} diff --git a/pkg/ai/prompt/examples.go b/pkg/ai/prompt/examples.go index 34231e32..566383c0 100644 --- a/pkg/ai/prompt/examples.go +++ b/pkg/ai/prompt/examples.go @@ -6,3 +6,8 @@ import "embed" // //go:embed testdata var Examples embed.FS + +// Builtin exposes the reusable prompts Captain ships, resolvable by name. +// +//go:embed builtin +var Builtin embed.FS From 43446cdeef107c008559880be8a95d5dacd07faa Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Thu, 22 Oct 2026 18:52:31 +0300 Subject: [PATCH 09/77] feat(api): add portable permissions.access compiled per runtime Authors can state read-only workspace access once with permissions.access. CompileAccess lowers it to each runtime's native dialect: per-tool denies on claude, a read-only sandbox with approval never on codex, and the plan approval mode on gemini. Layers resolve in order through ResolveAccessState, so a later layer can lift a read-only intent to full. A runtime that cannot reach the posture is refused rather than silently loosened, for example codex with the sandbox off or looser raw cmux flags. Fallback candidates are compiled and validated as they will run, so an unreachable fallback fails before the primary does. ConvertToAccess rewrites dialect-specific denies or sandboxes into the portable form only when the result is equivalent or tighter. Fallback substitution keeps the original runtime before crossing providers, so an agent is not moved to API mode and left without its tools. SpecLayer gains an Order field that sorts before scope. The YAML marshaller no longer re-emits raw opaque fields. BREAKING CHANGE: saved-spec resolution no longer defaults budget.maxTokens to 4096. The runtime now chooses the value, so callers that relied on 4096 must set it explicitly. --- pkg/api/access.go | 178 +++++++++++ pkg/api/access_compile.go | 281 ++++++++++++++++++ pkg/api/access_convert.go | 99 ++++++ pkg/api/access_ginkgo_test.go | 253 ++++++++++++++++ pkg/api/enums.go | 25 ++ pkg/api/permission_capabilities.go | 74 +++++ pkg/api/permissions.go | 43 ++- pkg/api/permissions_schema.go | 11 + pkg/api/registry/model.go | 37 ++- .../registry/model_disabled_ginkgo_test.go | 31 ++ pkg/api/spec_codec.go | 7 - pkg/api/spec_composition.go | 4 + pkg/api/spec_defaults.go | 4 - pkg/api/spec_defaults_ginkgo_test.go | 6 +- pkg/api/spec_layers.go | 12 +- pkg/api/spec_merge_differential_test.go | 7 + pkg/api/spec_presence_ginkgo_test.go | 14 + pkg/api/spec_runtime.go | 21 +- 18 files changed, 1073 insertions(+), 34 deletions(-) create mode 100644 pkg/api/access.go create mode 100644 pkg/api/access_compile.go create mode 100644 pkg/api/access_convert.go create mode 100644 pkg/api/access_ginkgo_test.go diff --git a/pkg/api/access.go b/pkg/api/access.go new file mode 100644 index 00000000..1f86d89b --- /dev/null +++ b/pkg/api/access.go @@ -0,0 +1,178 @@ +package api + +import ( + "fmt" + "slices" + "strings" +) + +// AccessDialect names the vocabulary an access intent was written in, and the +// one a runtime natively speaks: claude restricts per tool, codex through its +// sandbox and approval policy, gemini through an approval mode. +type AccessDialect string + +const ( + AccessDialectPortable AccessDialect = "portable" + AccessDialectTools AccessDialect = "tools" + AccessDialectSandbox AccessDialect = "sandbox" + AccessDialectApproval AccessDialect = "approval" +) + +// AccessState is the resolved access intent and where it came from, so +// `captain permissions explain` can name the layer and field that decided it. +type AccessState struct { + Level AccessLevel `json:"level"` + Dialect AccessDialect `json:"dialect"` + // Source is the field that set the state, e.g. permissions.access or + // permissions.tools. + Source string `json:"source"` + // Layer is the trace layer that set it; empty for a spec compiled without + // layer resolution. + Layer string `json:"layer,omitempty"` +} + +// ReadOnly reports whether the state restricts the run to read-only access. +func (s *AccessState) ReadOnly() bool { return s != nil && s.Level == AccessReadOnly } + +// readOnlyDeniedAliases are the shared aliases whose every carrier a read-only +// run must not reach. A tool-deny list covering all of them is the tool +// dialect's spelling of read-only. +var readOnlyDeniedAliases = []string{"edit", "write", "shell"} + +// writeAliases are the carriers a read-only sandbox already confines on codex +// but claude's sandbox does not, because it only wraps Bash. +var writeAliases = []string{"edit", "write"} + +// claudeSubAgentTools spawn agents that would not inherit a per-tool deny list. +var claudeSubAgentTools = []string{"Agent", "Task", "Workflow"} + +// EffectiveAccess is the access intent a runtime compiles: the layer-resolved +// state when the spec went through ResolveSpecLayers, otherwise the spec's own +// permissions.access, otherwise none. +func (p Permissions) EffectiveAccess() *AccessState { + if p.AccessState != nil { + return p.AccessState + } + if p.Access == "" { + return nil + } + return &AccessState{Level: p.Access, Dialect: AccessDialectPortable, Source: "permissions.access"} +} + +// ResolveAccessState walks ordered layers and keeps one access state, the later +// layer winning. A layer that sets permissions.access sets it outright; a layer +// whose own fields convert exactly (a tool-deny list covering every edit, write +// and shell carrier, or a native read-only sandbox) derives it; a layer that +// loosens a read-only state lifts it to full. Precedence is decided here, layer +// by layer, because the flattened spec no longer knows which layer wrote what. +func ResolveAccessState(layers []SpecLayer) (*AccessState, error) { + var state *AccessState + for _, layer := range layers { + next, err := layerAccessState(layer.Spec, state) + if err != nil { + return nil, fmt.Errorf("spec layer %q: %w", layer.Name, err) + } + if next != state && next != nil && next.Layer == "" { + next.Layer = layer.Name + } + state = next + } + return state, nil +} + +func layerAccessState(spec Spec, current *AccessState) (*AccessState, error) { + if resolved := spec.Permissions.AccessState; resolved != nil { + // An already-resolved spec re-entering as one layer keeps the verdict + // its own layers reached. + inherited := *resolved + return &inherited, nil + } + if level := spec.Permissions.Access; level != "" { + if allowed := toolsAllowing(spec.Permissions.Tools, readOnlyDeniedAliases); level == AccessReadOnly && len(allowed) > 0 { + return nil, fmt.Errorf("permissions.access read-only contradicts permissions.tools %s: allow in the same layer", + strings.Join(allowed, ", ")) + } + return &AccessState{Level: level, Dialect: AccessDialectPortable, Source: "permissions.access"}, nil + } + if derived := derivedAccessState(spec); derived != nil { + return derived, nil + } + if loosened := accessLoosening(spec); current.ReadOnly() && loosened != "" { + return &AccessState{Level: AccessFull, Dialect: current.Dialect, Source: loosened}, nil + } + return current, nil +} + +// derivedAccessState converts one layer's dialect-specific fields to read-only +// when they say exactly that. permissions.mode plan never converts: it permits +// the plan-file write. +func derivedAccessState(spec Spec) *AccessState { + if toolsDenyAll(spec.Permissions.Tools, readOnlyDeniedAliases) { + return &AccessState{Level: AccessReadOnly, Dialect: AccessDialectTools, Source: "permissions.tools"} + } + if nativeReadOnlySandbox(spec.Sandbox) { + return &AccessState{Level: AccessReadOnly, Dialect: AccessDialectSandbox, Source: "sandbox.policy.filesystem.access"} + } + return nil +} + +// accessLoosening names the first field of one spec that grants what read-only +// forbids, or "" when it grants nothing of the kind. +func accessLoosening(spec Spec) string { + if allowed := toolsAllowing(spec.Permissions.Tools, readOnlyDeniedAliases); len(allowed) > 0 { + return fmt.Sprintf("permissions.tools %s: allow", strings.Join(allowed, ", ")) + } + if ref := spec.Sandbox; ref != nil && ref.Mode != "" && ref.Mode != SandboxNative { + return fmt.Sprintf("sandbox mode %s", ref.Mode) + } + if fs := sandboxFilesystem(spec.Sandbox); fs != nil && fs.Access == SandboxFilesystemWorkspaceWrite { + return "sandbox.policy.filesystem.access workspace-write" + } + return "" +} + +func nativeReadOnlySandbox(ref *SandboxRef) bool { + fs := sandboxFilesystem(ref) + return ref != nil && ref.Mode == SandboxNative && fs != nil && fs.Access == SandboxFilesystemReadOnly +} + +func sandboxFilesystem(ref *SandboxRef) *SandboxFilesystemPolicy { + if ref == nil || ref.Policy == nil { + return nil + } + return ref.Policy.Filesystem +} + +// toolsDenyAll reports whether tools, read in the tool dialect's own vocabulary +// (claude's), deny every tool carrying one of the aliases outright. A patterned +// deny (`Bash(rm:*)`) restricts part of a tool and does not count. +func toolsDenyAll(tools Tools, aliases []string) bool { + if len(tools) == 0 { + return false + } + resolved, _ := tools.resolveForRuntime(Anthropic, ModeCLI) + for _, name := range aliasCarriers(agentTools["claude"], aliases) { + if resolved[name].policy != ToolPolicyDeny { + return false + } + } + return true +} + +// toolsAllowing lists the claude-vocabulary rules that allow a tool carrying +// one of the aliases, patterned or not. +func toolsAllowing(tools Tools, aliases []string) []string { + if len(tools) == 0 { + return nil + } + carriers := aliasCarriers(agentTools["claude"], aliases) + resolved, _ := tools.resolveForRuntime(Anthropic, ModeCLI) + var out []string + for _, rule := range sortedKeys(resolved) { + base, _, _ := strings.Cut(rule, "(") + if resolved[rule].policy == ToolPolicyAllow && slices.Contains(carriers, base) { + out = append(out, resolved[rule].describe(rule)) + } + } + return out +} diff --git a/pkg/api/access_compile.go b/pkg/api/access_compile.go new file mode 100644 index 00000000..a12f43ed --- /dev/null +++ b/pkg/api/access_compile.go @@ -0,0 +1,281 @@ +package api + +import ( + "fmt" + "maps" + "strings" +) + +// AccessReport is what CompileAccess did for one runtime, for explain output, +// run warnings and tests. +type AccessReport struct { + Runtime string `json:"runtime"` + Dialect AccessDialect `json:"dialect,omitempty"` + State *AccessState `json:"state,omitempty"` + // Unchanged marks an intent compiled in its own dialect, which passes + // through byte-identical. + Unchanged bool `json:"unchanged,omitempty"` + DeniedTools []string `json:"deniedTools,omitempty"` + Sandbox string `json:"sandbox,omitempty"` + Approval string `json:"approval,omitempty"` + Mode PermissionMode `json:"mode,omitempty"` + MCPDisabled bool `json:"mcpDisabled,omitempty"` + // Overridden are authored settings the compiled posture replaced. + Overridden []string `json:"overridden,omitempty"` + // Equivalences are authored tool denies a runtime without a tool filter + // cannot carry, accepted because the compiled posture already enforces them. + Equivalences []string `json:"equivalences,omitempty"` + Notes []string `json:"notes,omitempty"` +} + +// agentAccessDialects is the native dialect of each agent family's runtimes. +var agentAccessDialects = map[string]AccessDialect{ + "claude": AccessDialectTools, + "codex": AccessDialectSandbox, + "gemini": AccessDialectApproval, +} + +// RuntimeAccessDialect is the dialect a runtime natively expresses access in; +// empty for the API mode, which runs no built-in tools. +func RuntimeAccessDialect(runtime Runtime) AccessDialect { + p, ok := runtime.ModelProvider() + if !ok || runtime.Mode.Kind() != "cli" { + return "" + } + return agentAccessDialects[p.AgentName] +} + +type accessCompiler func(runtime Runtime, spec *Spec, state *AccessState, report *AccessReport) error + +var accessCompilers = map[AccessDialect]accessCompiler{ + AccessDialectTools: compileToolsAccess, + AccessDialectSandbox: compileSandboxAccess, + AccessDialectApproval: compileApprovalAccess, +} + +// CompileAccess compiles the spec's effective access intent into the runtime's +// native dialect. It is pure: the input is never mutated, and the result shares +// no map or sandbox the compiler changed. With no read-only intent, or for an +// intent written in the runtime's own dialect, the spec is returned unchanged. +// A posture the runtime cannot reach is an error, never a quieter run. +func CompileAccess(runtime Runtime, spec Spec) (Spec, AccessReport, error) { + state := spec.Permissions.EffectiveAccess() + report := AccessReport{Runtime: runtime.String(), Dialect: RuntimeAccessDialect(runtime), State: state} + if !state.ReadOnly() { + return spec, report, nil + } + if spec.Permissions.AccessState == nil { + if allowed := toolsAllowing(spec.Permissions.Tools, readOnlyDeniedAliases); len(allowed) > 0 { + return Spec{}, report, fmt.Errorf("%s: permissions.access read-only contradicts permissions.tools %s: allow", + runtime, strings.Join(allowed, ", ")) + } + } + compile, ok := accessCompilers[report.Dialect] + if !ok { + report.Notes = append(report.Notes, "no built-in file tools to restrict; caller tools stay governed by toolPolicy") + return spec, report, nil + } + out := spec.cloneForAccess() + if err := compile(runtime, &out, state, &report); err != nil { + return Spec{}, report, fmt.Errorf("%s: permissions.access read-only: %w", runtime, err) + } + return out, report, nil +} + +// cloneForAccess copies the parts of a spec an access compiler changes, so the +// caller's tool map and sandbox policy are never written through. +func (s Spec) cloneForAccess() Spec { + s.Permissions.Tools = maps.Clone(s.Permissions.Tools) + if s.Sandbox != nil { + ref := *s.Sandbox + if ref.Policy != nil { + policy := *ref.Policy + if policy.Filesystem != nil { + fs := *policy.Filesystem + policy.Filesystem = &fs + } + ref.Policy = &policy + } + s.Sandbox = &ref + } + return s +} + +// compileToolsAccess is claude's dialect. An intent derived from claude's own +// tool rules passes through; one derived from a read-only sandbox gains the +// Edit/Write denies claude's Bash-only sandbox cannot supply. +func compileToolsAccess(runtime Runtime, spec *Spec, state *AccessState, report *AccessReport) error { + p, _ := runtime.ModelProvider() + vocabulary := AgentToolsFor(p, runtime.Mode) + switch state.Dialect { + case AccessDialectTools: + report.Unchanged = true + report.Notes = append(report.Notes, "the authored tool rules are this runtime's own dialect and are used as-is") + case AccessDialectSandbox: + denyAccessTools(spec, report, aliasCarriers(vocabulary, writeAliases)) + report.Notes = append(report.Notes, "the sandbox confines Bash only, so edit and write tools are denied; Bash stays under the authored sandbox") + default: + denyAccessTools(spec, report, append(aliasCarriers(vocabulary, readOnlyDeniedAliases), claudeSubAgentTools...)) + spec.Permissions.MCP.Disabled = true + report.MCPDisabled = true + } + return nil +} + +func denyAccessTools(spec *Spec, report *AccessReport, names []string) { + if spec.Permissions.Tools == nil { + spec.Permissions.Tools = Tools{} + } + for _, name := range names { + if current, ok := spec.Permissions.Tools[name]; ok && current != ToolPolicyDeny { + report.Overridden = append(report.Overridden, fmt.Sprintf("permissions.tools %s: %s", name, current)) + } + spec.Permissions.Tools[name] = ToolPolicyDeny + report.DeniedTools = append(report.DeniedTools, name) + } +} + +// compileSandboxAccess is codex's dialect: a read-only native sandbox, approval +// never so no broker can grant an escalation, and no third-party MCP. An +// intent derived from a read-only sandbox already has its sandbox and only +// gains approval never. +func compileSandboxAccess(runtime Runtime, spec *Spec, state *AccessState, report *AccessReport) error { + cliPosture, err := codexCLIArgsPosture(runtime, spec.CLIArgs) + if err != nil { + return err + } + native := state.Dialect == AccessDialectSandbox + if !cliPosture && !native { + if err := confineCodexSandbox(spec); err != nil { + return err + } + } + if !cliPosture { + codexNeverApproval(runtime, spec, report) + } + if !native { + spec.Permissions.MCP.Disabled = true + report.MCPDisabled = true + } + report.Sandbox, report.Approval = string(CodexSandboxReadOnly), string(CodexApprovalNever) + stripEnforcedDenies(runtime, spec, report, "enforced by the read-only sandbox") + return nil +} + +// codexCLIArgsPosture reads cmux's raw codex flags. They bypass the sandbox +// translation entirely, so they must already say read-only and never; anything +// looser is refused rather than overridden behind the author's back. +func codexCLIArgsPosture(runtime Runtime, args map[string]any) (bool, error) { + if runtime.Mode != ModeCmux || (args["sandbox"] == nil && args["askForApproval"] == nil) { + return false, nil + } + sandbox, _ := args["sandbox"].(string) + approval, _ := args["askForApproval"].(string) + if sandbox == string(CodexSandboxReadOnly) && approval == string(CodexApprovalNever) { + return true, nil + } + return false, fmt.Errorf("cliArgs sandbox=%v askForApproval=%v is looser than read-only; set sandbox read-only and askForApproval never, or remove them", + args["sandbox"], args["askForApproval"]) +} + +func confineCodexSandbox(spec *Spec) error { + ref := spec.Sandbox + if ref == nil { + spec.Sandbox = &SandboxRef{Mode: SandboxNative, Policy: &NativeSandboxPolicy{ + Filesystem: &SandboxFilesystemPolicy{Access: SandboxFilesystemReadOnly}}} + return nil + } + if ref.Mode != SandboxNative { + return fmt.Errorf("sandbox mode %q cannot confine the agent; read-only needs the native sandbox", ref.Mode) + } + if ref.Policy == nil { + ref.Policy = &NativeSandboxPolicy{} + } + fs := ref.Policy.Filesystem + switch { + case fs == nil: + ref.Policy.Filesystem = &SandboxFilesystemPolicy{Access: SandboxFilesystemReadOnly} + case fs.Access == SandboxFilesystemWorkspaceWrite: + return fmt.Errorf("sandbox.policy.filesystem.access workspace-write grants the writes read-only forbids") + case len(fs.WritableRoots) > 0: + return fmt.Errorf("sandbox.policy.filesystem.writableRoots grants the writes read-only forbids") + default: + fs.Access = SandboxFilesystemReadOnly + } + return nil +} + +// codexNeverApproval sets the posture whose approval policy is never. The +// app-server's plan mode already refuses every escalation, so it is kept there. +func codexNeverApproval(runtime Runtime, spec *Spec, report *AccessReport) { + mode := spec.Permissions.Mode + if mode == PermissionPlan && runtime.Mode == ModeAgent { + report.Mode = mode + report.Equivalences = append(report.Equivalences, "permissions.mode plan: the app-server refuses every escalation request in plan mode") + return + } + if mode != "" && mode != PermissionBypass { + report.Overridden = append(report.Overridden, fmt.Sprintf("permissions.mode %s", mode)) + } + spec.Permissions.Mode = PermissionBypass + report.Mode = PermissionBypass +} + +// compileApprovalAccess is gemini's dialect: the plan approval mode. +func compileApprovalAccess(runtime Runtime, spec *Spec, _ *AccessState, report *AccessReport) error { + if mode := spec.Permissions.Mode; mode != "" && mode != PermissionPlan { + report.Overridden = append(report.Overridden, fmt.Sprintf("permissions.mode %s", mode)) + } + spec.Permissions.Mode = PermissionPlan + report.Mode = PermissionPlan + report.Notes = append(report.Notes, "plan mode is enforced by the gemini client, not an OS sandbox") + stripEnforcedDenies(runtime, spec, report, "enforced by the plan approval mode") + return nil +} + +// stripEnforcedDenies removes the authored denies the compiled posture already +// enforces on a runtime with no tool filter, recording each as an equivalence. +// A key is removed only when every tool it names is enforced, so a residual +// deny the posture does not cover still reaches RequireToolPolicySupport. +func stripEnforcedDenies(runtime Runtime, spec *Spec, report *AccessReport, enforcedBy string) { + p, _ := runtime.ModelProvider() + vocabulary := AgentToolsFor(p, runtime.Mode) + for _, key := range sortedKeys(spec.Permissions.Tools) { + if spec.Permissions.Tools[key] != ToolPolicyDeny { + continue + } + resolved, _ := Tools{key: ToolPolicyDeny}.resolveForRuntime(p, runtime.Mode) + var reasons []string + for _, rule := range sortedKeys(resolved) { + reason, ok := accessEnforcedDeny(vocabulary, rule, enforcedBy) + if !ok { + reasons = nil + break + } + reasons = append(reasons, resolved[rule].describe(rule)+": "+reason) + } + if len(reasons) > 0 { + delete(spec.Permissions.Tools, key) + report.Equivalences = append(report.Equivalences, reasons...) + } + } +} + +// accessEnforcedDeny reports whether a read-only posture compiled for a runtime +// without a tool filter enforces a deny on rule: an edit or write tool always; +// a shell only where the runtime has no shell-free read path, because there +// the shell is how it reads and the read-only sandbox confines it. +func accessEnforcedDeny(vocabulary []AgentTool, rule, enforcedBy string) (string, bool) { + base, _, _ := strings.Cut(rule, "(") + tool, ok := vocabularyTool(vocabulary, base, false) + switch { + case !ok: + return "", false + case len(aliasCarriers([]AgentTool{tool}, writeAliases)) > 0: + return enforcedBy, true + case len(aliasCarriers([]AgentTool{tool}, []string{"shell"})) > 0 && len(aliasCarriers(vocabulary, []string{"read"})) == 0: + return "kept as the read path, " + enforcedBy, true + default: + return "", false + } +} diff --git a/pkg/api/access_convert.go b/pkg/api/access_convert.go new file mode 100644 index 00000000..23bc9f71 --- /dev/null +++ b/pkg/api/access_convert.go @@ -0,0 +1,99 @@ +package api + +import ( + "fmt" + "slices" +) + +// ConversionResult is a dialect-specific permissions block rewritten into the +// portable access form. Permissions and Sandbox are the whole replacement: the +// access level plus every rule the conversion did not absorb. +type ConversionResult struct { + Convertible bool `json:"convertible"` + Dialect AccessDialect `json:"dialect,omitempty"` + Permissions Permissions `json:"permissions"` + Sandbox *SandboxRef `json:"sandbox,omitempty"` + // Residual describes the authored rules kept beside access, and Dropped the + // ones read-only already implies. + Residual []string `json:"residual,omitempty"` + Dropped []string `json:"dropped,omitempty"` + // Reason says why a spec could not be converted. + Reason string `json:"reason,omitempty"` +} + +// ConvertToAccess maps a dialect-specific spec to permissions.access only when +// the result is equivalent or tighter on every runtime: +// - tool denies covering every edit, write and shell tool become read-only, +// with any other rule (a web deny, a read allow) kept as a residual; +// - a native read-only sandbox with approval never (bypassPermissions) +// becomes read-only, keeping the rest of the sandbox. +// +// permissions.mode plan is never converted: it permits the plan-file write. +func ConvertToAccess(spec Spec) ConversionResult { + permissions := spec.Permissions + switch { + case permissions.Access != "": + return ConversionResult{Reason: fmt.Sprintf("permissions.access is already %s", permissions.Access)} + case toolsDenyAll(permissions.Tools, readOnlyDeniedAliases): + return convertToolsDialect(spec) + case nativeReadOnlySandbox(spec.Sandbox) && permissions.Mode == PermissionBypass: + return convertSandboxDialect(spec) + case permissions.Mode == PermissionPlan: + return ConversionResult{Reason: "permissions.mode plan permits the plan-file write, so it is not read-only"} + case nativeReadOnlySandbox(spec.Sandbox): + return ConversionResult{Reason: "a read-only sandbox still lets a broker approve escalated writes; add permissions.mode bypassPermissions (approval never) to convert it"} + default: + return ConversionResult{Reason: "no exact read-only form: permissions.tools does not deny every edit, write and shell tool, and the sandbox is not native read-only"} + } +} + +func convertToolsDialect(spec Spec) ConversionResult { + out := ConversionResult{Convertible: true, Dialect: AccessDialectTools, Permissions: spec.Permissions, Sandbox: spec.Sandbox} + out.Permissions.Access = AccessReadOnly + out.Permissions.AccessState = nil + out.Permissions.Tools = nil + carriers := aliasCarriers(agentTools["claude"], readOnlyDeniedAliases) + for _, key := range sortedKeys(spec.Permissions.Tools) { + policy := spec.Permissions.Tools[key] + rule := fmt.Sprintf("permissions.tools %s: %s", key, policy) + if policy == ToolPolicyDeny && namesOnly(Tools{key: policy}, carriers) { + out.Dropped = append(out.Dropped, rule) + continue + } + out.Permissions.Tools.put(key, policy) + out.Residual = append(out.Residual, rule) + } + return out +} + +// namesOnly reports whether every claude tool the rules reach is one of names. +func namesOnly(tools Tools, names []string) bool { + resolved, _ := tools.resolveForRuntime(Anthropic, ModeCLI) + for rule := range resolved { + if !slices.Contains(names, rule) { + return false + } + } + return len(resolved) > 0 +} + +func convertSandboxDialect(spec Spec) ConversionResult { + out := ConversionResult{Convertible: true, Dialect: AccessDialectSandbox, Permissions: spec.Permissions} + out.Permissions.Access = AccessReadOnly + out.Permissions.AccessState = nil + out.Permissions.Mode = "" + out.Dropped = []string{"permissions.mode bypassPermissions", "sandbox.policy.filesystem.access read-only"} + ref := spec.cloneForAccess().Sandbox + ref.Policy.Filesystem.Access = "" + if IsEmpty(*ref.Policy.Filesystem) { + ref.Policy.Filesystem = nil + } + if IsEmpty(*ref.Policy) { + ref.Policy = nil + } + out.Sandbox = ref + for _, key := range sortedKeys(spec.Permissions.Tools) { + out.Residual = append(out.Residual, fmt.Sprintf("permissions.tools %s: %s", key, spec.Permissions.Tools[key])) + } + return out +} diff --git a/pkg/api/access_ginkgo_test.go b/pkg/api/access_ginkgo_test.go new file mode 100644 index 00000000..f85890ce --- /dev/null +++ b/pkg/api/access_ginkgo_test.go @@ -0,0 +1,253 @@ +package api + +import ( + "encoding/json" + + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" + "gopkg.in/yaml.v3" +) + +var ( + readOnlyTools = Tools{"edit": ToolPolicyDeny, "write": ToolPolicyDeny, "shell": ToolPolicyDeny} + readOnlyFS = &SandboxRef{Mode: SandboxNative, Policy: &NativeSandboxPolicy{ + Filesystem: &SandboxFilesystemPolicy{Access: SandboxFilesystemReadOnly}}} + claudeAgent = RuntimeOf(Anthropic, ModeAgent) + codexAgent = RuntimeOf(OpenAI, ModeAgent) + codexCmux = RuntimeOf(OpenAI, ModeCmux) + geminiCLI = RuntimeOf(Google, ModeCLI) +) + +func explicitReadOnly(spec Spec) Spec { + spec.Permissions.Access = AccessReadOnly + return spec +} + +func derived(spec Spec, dialect AccessDialect, source string) Spec { + spec.Permissions.AccessState = &AccessState{Level: AccessReadOnly, Dialect: dialect, Source: source, Layer: "preset"} + return spec +} + +var _ = Describe("permissions.access", func() { + DescribeTable("decodes, validates and round-trips", + func(document string, want AccessLevel, wantErr string) { + var spec Spec + Expect(yaml.Unmarshal([]byte(document), &spec)).To(Succeed()) + err := spec.ValidateStructure() + if wantErr != "" { + Expect(err).To(MatchError(ContainSubstring(wantErr))) + return + } + Expect(err).NotTo(HaveOccurred()) + Expect(spec.Permissions.Access).To(Equal(want)) + encoded, err := json.Marshal(spec) + Expect(err).NotTo(HaveOccurred()) + var again Spec + Expect(json.Unmarshal(encoded, &again)).To(Succeed()) + Expect(again.Permissions.Access).To(Equal(want)) + }, + Entry("read-only", "permissions: {access: read-only}", AccessReadOnly, ""), + Entry("full", "permissions: {access: full}", AccessFull, ""), + Entry("unknown level", "permissions: {access: workspace-write}", AccessLevel(""), `invalid permissions access "workspace-write"`), + ) + + It("leaves an unset access out of the encoded spec", func() { + encoded, err := json.Marshal(Spec{Permissions: Permissions{Mode: PermissionPlan}}) + Expect(err).NotTo(HaveOccurred()) + Expect(string(encoded)).NotTo(ContainSubstring("access")) + }) +}) + +var _ = Describe("ResolveAccessState", func() { + layer := func(name string, spec Spec) SpecLayer { + return SpecLayer{Name: name, Scope: SpecLayerContext, Spec: spec} + } + DescribeTable("canonicalizes each layer, then the later layer wins", + func(layers []SpecLayer, want *AccessState) { + Expect(ResolveAccessState(layers)).To(Equal(want)) + }, + Entry("no access anywhere", []SpecLayer{layer("a", Spec{Permissions: Permissions{Mode: PermissionAuto}})}, nil), + Entry("explicit read-only", + []SpecLayer{layer("prompt", Spec{Permissions: Permissions{Access: AccessReadOnly}})}, + &AccessState{Level: AccessReadOnly, Dialect: AccessDialectPortable, Source: "permissions.access", Layer: "prompt"}), + Entry("a preset read-only overridden by a request full", + []SpecLayer{layer("preset", Spec{Permissions: Permissions{Access: AccessReadOnly}}), layer("request", Spec{Permissions: Permissions{Access: AccessFull}})}, + &AccessState{Level: AccessFull, Dialect: AccessDialectPortable, Source: "permissions.access", Layer: "request"}), + Entry("tool denies covering every edit, write and shell carrier", + []SpecLayer{layer("read-only", Spec{Permissions: Permissions{Tools: readOnlyTools}})}, + &AccessState{Level: AccessReadOnly, Dialect: AccessDialectTools, Source: "permissions.tools", Layer: "read-only"}), + Entry("claude names that leave Monitor and MultiEdit reachable do not convert", + []SpecLayer{layer("a", Spec{Permissions: Permissions{Tools: Tools{"Bash": ToolPolicyDeny, "Edit": ToolPolicyDeny, "Write": ToolPolicyDeny}}})}, nil), + Entry("a native read-only sandbox", + []SpecLayer{layer("box", Spec{Sandbox: readOnlyFS})}, + &AccessState{Level: AccessReadOnly, Dialect: AccessDialectSandbox, Source: "sandbox.policy.filesystem.access", Layer: "box"}), + Entry("plan mode never converts", + []SpecLayer{layer("plan", Spec{Permissions: Permissions{Mode: PermissionPlan, Tools: Tools{"shell": ToolPolicyDeny}}})}, nil), + Entry("a later shell allow lifts a derived read-only", + []SpecLayer{layer("preset", Spec{Permissions: Permissions{Tools: readOnlyTools}}), layer("request", Spec{Permissions: Permissions{Tools: Tools{"Bash": ToolPolicyAllow}}})}, + &AccessState{Level: AccessFull, Dialect: AccessDialectTools, Source: "permissions.tools Bash: allow", Layer: "request"}), + Entry("a later sandbox off lifts a sandbox read-only", + []SpecLayer{layer("box", Spec{Sandbox: readOnlyFS}), layer("request", Spec{Sandbox: &SandboxRef{Mode: SandboxOff}})}, + &AccessState{Level: AccessFull, Dialect: AccessDialectSandbox, Source: "sandbox mode off", Layer: "request"}), + Entry("a later layer that grants nothing keeps the intent", + []SpecLayer{layer("preset", Spec{Permissions: Permissions{Tools: readOnlyTools}}), layer("prompt", Spec{Permissions: Permissions{Tools: Tools{"Read": ToolPolicyAllow}}})}, + &AccessState{Level: AccessReadOnly, Dialect: AccessDialectTools, Source: "permissions.tools", Layer: "preset"}), + ) + + It("refuses read-only and a shell allow in the same layer", func() { + _, err := ResolveAccessState([]SpecLayer{layer("prompt", Spec{Permissions: Permissions{Access: AccessReadOnly, Tools: Tools{"Bash": ToolPolicyAllow}}})}) + Expect(err).To(MatchError(ContainSubstring(`spec layer "prompt": permissions.access read-only contradicts permissions.tools Bash: allow`))) + }) + + It("records the state on the resolved spec and its permissions", func() { + resolved, err := ResolveSpecLayers(ResolveSpecOptions{Layers: []SpecLayer{ + PromptSpecLayer("prompt", Spec{Model: Model{Name: "agent:sonnet"}, Permissions: Permissions{Tools: readOnlyTools}})}}) + Expect(err).NotTo(HaveOccurred()) + want := &AccessState{Level: AccessReadOnly, Dialect: AccessDialectTools, Source: "permissions.tools", Layer: "prompt"} + Expect(resolved.Access).To(Equal(want)) + Expect(resolved.Spec.Permissions.AccessState).To(Equal(want)) + }) +}) + +var _ = Describe("CompileAccess", func() { + DescribeTable("compiles read-only to each runtime's native dialect", + func(runtime Runtime, spec Spec, wantTools Tools, wantSandbox *SandboxRef, wantMode PermissionMode, wantMCP bool) { + compiled, _, err := CompileAccess(runtime, spec) + Expect(err).NotTo(HaveOccurred()) + Expect(compiled.Permissions.Tools).To(Equal(wantTools)) + Expect(compiled.Sandbox).To(Equal(wantSandbox)) + Expect(compiled.Permissions.Mode).To(Equal(wantMode)) + Expect(compiled.Permissions.MCP.Disabled).To(Equal(wantMCP)) + }, + Entry("claude: every edit, write and shell carrier plus sub-agents, and no MCP", + claudeAgent, explicitReadOnly(Spec{Sandbox: &SandboxRef{Mode: SandboxOff}}), + Tools{"Bash": ToolPolicyDeny, "BashOutput": ToolPolicyDeny, "KillShell": ToolPolicyDeny, "Monitor": ToolPolicyDeny, + "Edit": ToolPolicyDeny, "MultiEdit": ToolPolicyDeny, "NotebookEdit": ToolPolicyDeny, "Write": ToolPolicyDeny, + "Agent": ToolPolicyDeny, "Task": ToolPolicyDeny, "Workflow": ToolPolicyDeny}, + &SandboxRef{Mode: SandboxOff}, PermissionMode(""), true), + Entry("claude: a tool-derived intent passes through untouched", + claudeAgent, derived(Spec{Permissions: Permissions{Tools: readOnlyTools}}, AccessDialectTools, "permissions.tools"), + readOnlyTools, (*SandboxRef)(nil), PermissionMode(""), false), + Entry("claude: a sandbox-derived intent adds the edit and write denies its sandbox cannot", + claudeAgent, derived(Spec{Sandbox: readOnlyFS}, AccessDialectSandbox, "sandbox.policy.filesystem.access"), + Tools{"Edit": ToolPolicyDeny, "MultiEdit": ToolPolicyDeny, "NotebookEdit": ToolPolicyDeny, "Write": ToolPolicyDeny}, + readOnlyFS, PermissionMode(""), false), + Entry("codex: native read-only sandbox, approval never and no MCP", + codexAgent, explicitReadOnly(Spec{}), Tools(nil), readOnlyFS, PermissionBypass, true), + Entry("codex: a tool-derived intent drops the denies the sandbox enforces", + codexAgent, derived(Spec{Permissions: Permissions{Tools: readOnlyTools}}, AccessDialectTools, "permissions.tools"), + Tools{}, readOnlyFS, PermissionBypass, true), + Entry("codex: a sandbox-derived intent keeps its sandbox and only stops asking", + codexAgent, derived(Spec{Sandbox: readOnlyFS}, AccessDialectSandbox, "sandbox.policy.filesystem.access"), + Tools(nil), readOnlyFS, PermissionBypass, false), + Entry("codex agent: plan already refuses every escalation and is kept", + codexAgent, explicitReadOnly(Spec{Permissions: Permissions{Mode: PermissionPlan}}), Tools(nil), readOnlyFS, PermissionPlan, true), + Entry("codex cmux: raw flags that already say read-only and never are kept", + codexCmux, explicitReadOnly(Spec{CLIArgs: map[string]any{"sandbox": "read-only", "askForApproval": "never"}}), + Tools(nil), (*SandboxRef)(nil), PermissionMode(""), true), + Entry("gemini: the plan approval mode", + geminiCLI, explicitReadOnly(Spec{Permissions: Permissions{Mode: PermissionBypass}}), Tools(nil), (*SandboxRef)(nil), PermissionPlan, false), + Entry("api: nothing to restrict", + RuntimeOf(Anthropic, ModeAPI), explicitReadOnly(Spec{}), Tools(nil), (*SandboxRef)(nil), PermissionMode(""), false), + ) + + DescribeTable("refuses a posture the runtime cannot reach", + func(runtime Runtime, spec Spec, want string) { + _, _, err := CompileAccess(runtime, explicitReadOnly(spec)) + Expect(err).To(MatchError(ContainSubstring(want))) + }, + Entry("codex with the sandbox off", codexAgent, Spec{Sandbox: &SandboxRef{Mode: SandboxOff}}, `sandbox mode "off" cannot confine the agent`), + Entry("codex with a docker sandbox", codexAgent, Spec{Sandbox: &SandboxRef{Mode: SandboxDocker}}, `sandbox mode "docker" cannot confine the agent`), + Entry("codex with a workspace-write sandbox", codexAgent, Spec{Sandbox: &SandboxRef{Mode: SandboxNative, Policy: &NativeSandboxPolicy{ + Filesystem: &SandboxFilesystemPolicy{Access: SandboxFilesystemWorkspaceWrite}}}}, "workspace-write grants the writes"), + Entry("codex cmux with looser raw flags", codexCmux, Spec{CLIArgs: map[string]any{"sandbox": "workspace-write"}}, "cliArgs sandbox=workspace-write"), + Entry("any runtime with a shell allow beside read-only", claudeAgent, Spec{Permissions: Permissions{Tools: Tools{"shell": ToolPolicyAllow}}}, + "contradicts permissions.tools"), + ) + + It("never mutates the input spec", func() { + input := derived(Spec{Permissions: Permissions{Tools: Tools{"edit": ToolPolicyDeny, "write": ToolPolicyDeny, "shell": ToolPolicyDeny, "Read": ToolPolicyAllow}}, + Sandbox: &SandboxRef{Mode: SandboxNative, Policy: &NativeSandboxPolicy{Filesystem: &SandboxFilesystemPolicy{}}}}, + AccessDialectTools, "permissions.tools") + before, err := json.Marshal(input) + Expect(err).NotTo(HaveOccurred()) + for _, runtime := range []Runtime{claudeAgent, codexAgent, geminiCLI} { + _, _, _ = CompileAccess(runtime, input) + } + after, err := json.Marshal(input) + Expect(err).NotTo(HaveOccurred()) + Expect(string(after)).To(Equal(string(before))) + Expect(input.Sandbox.Policy.Filesystem.Access).To(BeEmpty()) + }) + + It("reports the codex shell as an explicit equivalence", func() { + _, report, err := CompileAccess(codexAgent, derived(Spec{Permissions: Permissions{Tools: Tools{"Bash": ToolPolicyDeny}}}, AccessDialectTools, "permissions.tools")) + Expect(err).NotTo(HaveOccurred()) + Expect(report.Equivalences).To(ConsistOf( + "exec (from Bash): kept as the read path, enforced by the read-only sandbox", + "exec_command (from Bash): kept as the read path, enforced by the read-only sandbox", + "shell (from Bash): kept as the read path, enforced by the read-only sandbox", + "write_stdin (from Bash): kept as the read path, enforced by the read-only sandbox", + )) + }) + + It("agrees with the matrix's codex cell and the sandbox translator", func() { + compiled, _, err := CompileAccess(codexAgent, explicitReadOnly(Spec{})) + Expect(err).NotTo(HaveOccurred()) + translation, err := TranslateCodexSandbox(codexAgent, compiled.Sandbox, compiled.Permissions.Mode) + Expect(err).NotTo(HaveOccurred()) + cell := PermissionCapabilitiesFor(codexAgent).AccessSupport(AccessReadOnly) + Expect(string(translation.Sandbox)).To(Equal(cell.Effects.Sandbox)) + Expect(string(translation.Approval)).To(Equal(cell.Effects.Approval)) + }) +}) + +var _ = Describe("ConvertToAccess", func() { + DescribeTable("rewrites a dialect only when the portable form is equivalent or tighter", + func(spec Spec, want ConversionResult) { + Expect(ConvertToAccess(spec)).To(Equal(want)) + }, + Entry("the read-only preset keeps its web denies as residuals", + Spec{Permissions: Permissions{Tools: Tools{"edit": ToolPolicyDeny, "write": ToolPolicyDeny, "shell": ToolPolicyDeny, + "web_search": ToolPolicyDeny, "web_fetch": ToolPolicyDeny}}}, + ConversionResult{Convertible: true, Dialect: AccessDialectTools, + Permissions: Permissions{Access: AccessReadOnly, Tools: Tools{"web_fetch": ToolPolicyDeny, "web_search": ToolPolicyDeny}}, + Residual: []string{"permissions.tools web_fetch: deny", "permissions.tools web_search: deny"}, + Dropped: []string{"permissions.tools edit: deny", "permissions.tools shell: deny", "permissions.tools write: deny"}}), + Entry("a native read-only sandbox with approval never", + Spec{Permissions: Permissions{Mode: PermissionBypass}, Sandbox: readOnlyFS}, + ConversionResult{Convertible: true, Dialect: AccessDialectSandbox, + Permissions: Permissions{Access: AccessReadOnly}, Sandbox: &SandboxRef{Mode: SandboxNative}, + Dropped: []string{"permissions.mode bypassPermissions", "sandbox.policy.filesystem.access read-only"}}), + Entry("plan mode permits the plan-file write", + Spec{Permissions: Permissions{Mode: PermissionPlan, Tools: Tools{"read": ToolPolicyAllow, "shell": ToolPolicyDeny}}}, + ConversionResult{Reason: "permissions.mode plan permits the plan-file write, so it is not read-only"}), + Entry("a read-only sandbox that a broker could still escalate", + Spec{Sandbox: readOnlyFS}, + ConversionResult{Reason: "a read-only sandbox still lets a broker approve escalated writes; add permissions.mode bypassPermissions (approval never) to convert it"}), + ) +}) + +var _ = Describe("RequireToolPolicySupport under read-only", func() { + DescribeTable("accepts only the denies the compiled posture enforces", + func(runtime Runtime, tools Tools, want string) { + p, _ := runtime.ModelProvider() + err := RequireToolPolicySupport(p, runtime.Mode, Permissions{Access: AccessReadOnly, Tools: tools}) + if want == "" { + Expect(err).NotTo(HaveOccurred()) + return + } + Expect(err).To(MatchError(ContainSubstring(want))) + }, + Entry("codex: edit, write and its shell read path", codexAgent, readOnlyTools, ""), + Entry("codex: web search is still refused", codexAgent, Tools{"web_search": ToolPolicyDeny}, "web_search"), + Entry("gemini: edit and write", geminiCLI, Tools{"edit": ToolPolicyDeny, "write": ToolPolicyDeny}, ""), + Entry("gemini: the shell is not its read path", geminiCLI, Tools{"shell": ToolPolicyDeny}, "run_shell_command"), + ) + + It("suggests the portable form when the rules already say read-only", func() { + p, _ := codexAgent.ModelProvider() + err := RequireToolPolicySupport(p, codexAgent.Mode, Permissions{Tools: readOnlyTools}) + Expect(err).To(MatchError(ContainSubstring("permissions: {access: read-only}"))) + }) +}) diff --git a/pkg/api/enums.go b/pkg/api/enums.go index ba27f18f..dbfb1ff7 100644 --- a/pkg/api/enums.go +++ b/pkg/api/enums.go @@ -223,6 +223,31 @@ func (m PermissionMode) Valid() bool { return false } +// AccessLevel is the portable access contract (permissions.access). It states +// what the agent may do to the workspace once, and CompileAccess turns it into +// each runtime's own dialect: per-tool denies on claude, a sandbox and approval +// policy on codex, an approval mode on gemini. Unset leaves every runtime as it +// was. +type AccessLevel string + +const ( + // AccessReadOnly may read the workspace but not create, modify or delete + // files, spawn sub-agents, use third-party MCP servers, or gain write access + // by approval. + AccessReadOnly AccessLevel = "read-only" + // AccessFull adds nothing: it states that no access restriction applies, + // which overrides a read-only intent inherited from an earlier layer. + AccessFull AccessLevel = "full" +) + +// AllAccessLevels lists the access levels in canonical order. +func AllAccessLevels() []AccessLevel { return []AccessLevel{AccessReadOnly, AccessFull} } + +// Valid reports whether a is a recognised access level (including ""). +func (a AccessLevel) Valid() bool { + return a == "" || a == AccessReadOnly || a == AccessFull +} + // Preset is a named bundle of safety defaults applied before per-tool rules. type Preset string diff --git a/pkg/api/permission_capabilities.go b/pkg/api/permission_capabilities.go index cf7c0ded..861a6335 100644 --- a/pkg/api/permission_capabilities.go +++ b/pkg/api/permission_capabilities.go @@ -133,6 +133,9 @@ type PermissionCapabilities struct { // skills are enforced by omission before reaching any provider. One Support per kind would // report "supported" for a request that is silently ignored. Resources map[ResourceKind]map[ResourceMode]Support `json:"resources"` + // Access is what permissions.access compiles to on this runtime; see + // CompileAccess, which these cells are pinned against. + Access map[AccessLevel]Support `json:"access"` // Tools is the runtime's built-in tool vocabulary — the names a per-tool // policy can legitimately mention for ProvenanceAgent. Tools []string `json:"tools,omitempty"` @@ -167,6 +170,14 @@ func (c PermissionCapabilities) ResourceSupport(kind ResourceKind, mode Resource return Support{Kind: SupportUnsupported} } +// AccessSupport returns the cell for one access level. +func (c PermissionCapabilities) AccessSupport(level AccessLevel) Support { + if s, ok := c.Access[level]; ok { + return s + } + return Support{Kind: SupportUnsupported} +} + // PermissionCapabilitiesFor returns the declared surface for a runtime. An // unknown runtime gets a fully-unsupported row rather than a zero value, so a // caller that forgets to check still fails closed. @@ -178,9 +189,22 @@ func PermissionCapabilitiesFor(runtime Runtime) PermissionCapabilities { Modes: unsupportedModes(), ToolPolicies: toolPolicies(noToolFilter(), noToolFilter(), noToolFilter()), Resources: resources(false, false), + Access: access(unsupported("unknown runtime: no access compiler")), } } +// ToolPolicyRuntimes lists the runtimes whose agent built-ins honour a tool +// deny, in canonical order, for refusal text. +func ToolPolicyRuntimes() []Runtime { + var out []Runtime + for _, runtime := range PermissionCapabilityRuntimes() { + if PermissionCapabilitiesFor(runtime).ToolPolicySupport(ProvenanceAgent, ToolPolicyDeny).Honoured() { + out = append(out, runtime) + } + } + return out +} + // PermissionCapabilityRuntimes lists the runtimes the table declares, in // canonical AllRuntimes order. func PermissionCapabilityRuntimes() []Runtime { @@ -309,6 +333,44 @@ func resources(mcpOff, skillsOn bool) map[ResourceKind]map[ResourceMode]Support } } +// access builds the permissions.access row. full adds nothing anywhere, so it is +// native everywhere a compiler exists; read-only is the cell that differs. +func access(readOnly Support) map[AccessLevel]Support { + full := native("") + if readOnly.Kind == SupportUnsupported { + full = readOnly + } + return map[AccessLevel]Support{AccessReadOnly: readOnly, AccessFull: full} +} + +// apiAccess: the API mode runs no built-in file tools, so read-only already +// holds; caller tools stay governed by toolPolicy, outside the access contract. +func apiAccess() map[AccessLevel]Support { + return access(nativeNote("", "no built-in file tools to restrict; caller tools stay governed by toolPolicy")) +} + +// claudeAccess: the tool dialect, compiled to per-tool denies. +func claudeAccess() map[AccessLevel]Support { + return access(nativeNote("--disallowedTools", + "denies every edit, write and shell carrier plus Agent, Task and Workflow, and disables third-party MCP servers")) +} + +// codexAccess: the sandbox dialect. Codex reads through its shell, so the shell +// stays, confined by the read-only sandbox, and approval never removes the +// escalation path a broker could otherwise grant. +func codexAccess() map[AccessLevel]Support { + return access(Support{Kind: SupportNative, Effects: PermissionEffects{ + Sandbox: string(CodexSandboxReadOnly), Approval: string(CodexApprovalNever), + Note: "the shell stays as codex's read path, confined by the read-only sandbox; third-party MCP servers are disabled", + }}) +} + +// geminiAccess: the approval dialect, which the gemini client enforces itself. +func geminiAccess() map[AccessLevel]Support { + return access(approxFlag("--approval-mode plan", + "plan mode is enforced by the gemini client rather than an OS sandbox, and gemini has no per-run MCP override")) +} + // claudeModes is the posture row shared by every claude transport: the enum was // modelled on `claude --permission-mode`, so all six map one-to-one. // @@ -403,26 +465,31 @@ var permissionCapabilities = map[Runtime]PermissionCapabilities{ Modes: unsupportedModes(), ToolPolicies: toolPolicies(noToolFilter(), callerTools(), noToolFilter()), Resources: resources(false, false), + Access: apiAccess(), }, RuntimeOf(OpenAI, ModeAPI): { Modes: unsupportedModes(), ToolPolicies: toolPolicies(noToolFilter(), callerTools(), noToolFilter()), Resources: resources(false, false), + Access: apiAccess(), }, RuntimeOf(Google, ModeAPI): { Modes: unsupportedModes(), ToolPolicies: toolPolicies(noToolFilter(), callerTools(), noToolFilter()), Resources: resources(false, false), + Access: apiAccess(), }, RuntimeOf(DeepSeek, ModeAPI): { Modes: unsupportedModes(), ToolPolicies: toolPolicies(noToolFilter(), callerTools(), noToolFilter()), Resources: resources(false, false), + Access: apiAccess(), }, RuntimeOf(Jev, ModeAPI): { Modes: unsupportedModes(), ToolPolicies: toolPolicies(noToolFilter(), noToolFilter(), noToolFilter()), Resources: resources(false, false), + Access: apiAccess(), }, // bash runs a command, with no tools to filter and no resources to load. RuntimeOf(Bash, ModeAPI): { @@ -440,6 +507,7 @@ var permissionCapabilities = map[Runtime]PermissionCapabilities{ // loads skills. Resources: resources(true, true), Tools: claudeBuiltinTools, + Access: claudeAccess(), }, RuntimeOf(Anthropic, ModeAgent): { Modes: claudeModes("permissionMode=", true), @@ -449,6 +517,7 @@ var permissionCapabilities = map[Runtime]PermissionCapabilities{ // server is the only one that survives mcp.disabled. Resources: resources(true, false), Tools: claudeBuiltinTools, + Access: claudeAccess(), }, RuntimeOf(Anthropic, ModeCmux): { Modes: claudeModes("--permission-mode ", true), @@ -457,6 +526,7 @@ var permissionCapabilities = map[Runtime]PermissionCapabilities{ // server, or an empty --mcp-config when there are no caller tools. Resources: resources(true, false), Tools: claudeBuiltinTools, + Access: claudeAccess(), }, // --- codex transports: posture is a sandbox/approval pair, never a mode. @@ -467,6 +537,7 @@ var permissionCapabilities = map[Runtime]PermissionCapabilities{ // server, or with an empty table when there are no caller tools. Resources: resources(true, false), Tools: codexBuiltinTools, + Access: codexAccess(), }, RuntimeOf(OpenAI, ModeAgent): { Modes: codexModes(true), @@ -478,6 +549,7 @@ var permissionCapabilities = map[Runtime]PermissionCapabilities{ // server in mcp_servers, or an empty map when there are no caller tools. Resources: resources(true, false), Tools: codexBuiltinTools, + Access: codexAccess(), }, RuntimeOf(OpenAI, ModeCmux): { Modes: codexModes(false), @@ -485,6 +557,7 @@ var permissionCapabilities = map[Runtime]PermissionCapabilities{ // Same mcp_servers override as codex-cli. Resources: resources(true, false), Tools: codexBuiltinTools, + Access: codexAccess(), }, // --- gemini CLI: an approval-mode flag and nothing else. The provider @@ -494,5 +567,6 @@ var permissionCapabilities = map[Runtime]PermissionCapabilities{ ToolPolicies: toolPolicies(noToolFilter(), noToolFilter(), noToolFilter()), Resources: resources(false, false), Tools: geminiBuiltinTools, + Access: geminiAccess(), }, } diff --git a/pkg/api/permissions.go b/pkg/api/permissions.go index 2e61b42c..ff4daa23 100644 --- a/pkg/api/permissions.go +++ b/pkg/api/permissions.go @@ -22,6 +22,17 @@ import ( type Permissions struct { // Mode is the base permission posture, independent of any sandbox. Mode PermissionMode `json:"mode,omitempty" yaml:"mode,omitempty" pretty:"label=Mode"` + // Access is the portable access contract, compiled per runtime by + // CompileAccess. Unset leaves every runtime's output unchanged. + Access AccessLevel `json:"access,omitempty" yaml:"access,omitempty" pretty:"label=Access"` + // AccessState is the access intent ResolveSpecLayers derived layer by layer, + // including an intent converted from another dialect (a tool-deny list, a + // read-only native sandbox). It cannot be recomputed from the flattened spec, + // because the fold forgets which layer wrote a key, so it rides on the spec + // to the provider decorator that compiles it. It is runtime state, never + // serialized: a spec that crosses a process boundary loses it and is then + // compiled from Access alone, which refuses rather than loosens. + AccessState *AccessState `json:"-" yaml:"-" pretty:"-"` // Presets are named safety bundles applied before per-tool rules. (--edit/--bare) Presets []Preset `json:"presets,omitempty" yaml:"presets,omitempty" pretty:"label=Presets"` // Tools is the per-tool allow/deny/mode policy. @@ -167,6 +178,12 @@ func (t Tools) toolsWithPolicy(want ToolPolicy) []string { // another name, and dropping the deny would hand the agent the very tool the // spec forbade. // +// Support is read from the capability matrix. Under a read-only access intent, +// a deny the compiled posture already enforces is accepted rather than refused: +// an edit or write tool everywhere, and a shell where it is the runtime's only +// read path (codex), confined by the read-only sandbox. CompileAccess reports +// each one as an equivalence. +// // `ask` is refused everywhere, on the authored keys and before translation: no // transport has a per-tool prompt, so it would resolve to "allowed" on the // runtimes that advertise tool policy support. `auto` constrains nothing, so it @@ -177,19 +194,32 @@ func RequireToolPolicySupport(p *ModelProvider, mode RuntimeMode, permissions Pe "per-tool policy \"ask\" (%s) is not enforceable on any runtime: transports carry allow/deny tool lists only, so the tool would run unprompted; use allow or deny", strings.Join(asked, ", ")) } + runtime := RuntimeOf(p, mode) + caps := PermissionCapabilitiesFor(runtime) + readOnly := permissions.EffectiveAccess().ReadOnly() + vocabulary := AgentToolsFor(p, mode) resolved, _ := permissions.Tools.resolveForRuntime(p, mode) var enforced []string for _, rule := range sortedKeys(resolved) { - if tool := resolved[rule]; tool.policy == ToolPolicyAllow || tool.policy == ToolPolicyDeny { - enforced = append(enforced, tool.describe(rule)) + tool := resolved[rule] + if tool.policy != ToolPolicyAllow && tool.policy != ToolPolicyDeny || caps.ToolPolicySupport(ProvenanceAgent, tool.policy).Honoured() { + continue + } + if _, ok := accessEnforcedDeny(vocabulary, rule, ""); readOnly && ok && tool.policy == ToolPolicyDeny { + continue } + enforced = append(enforced, tool.describe(rule)) } - if len(enforced) == 0 || registry.SupportsToolPolicy(p, mode) { + if len(enforced) == 0 { return nil } + hint := "" + if !readOnly && toolsDenyAll(permissions.Tools, readOnlyDeniedAliases) { + hint = "; these rules deny every edit, write and shell tool, which is permissions: {access: read-only} — `captain permissions convert ` rewrites them" + } return fmt.Errorf( - "%s cannot enforce a per-tool policy (%s), and running without it would grant more than the spec allows; remove permissions.tools or use one of: %s", - registry.RuntimeOf(p, mode), strings.Join(enforced, ", "), registry.RuntimesList(registry.ToolPolicyRuntimes())) + "%s cannot enforce a per-tool policy (%s), and running without it would grant more than the spec allows; remove permissions.tools or use one of: %s%s", + runtime, strings.Join(enforced, ", "), registry.RuntimesList(ToolPolicyRuntimes()), hint) } // Validate checks the mode, presets, tool policies, and resource modes are @@ -198,6 +228,9 @@ func (p Permissions) Validate() error { if !p.Mode.Valid() { return fmt.Errorf("invalid permission mode %q", p.Mode) } + if !p.Access.Valid() { + return fmt.Errorf("invalid permissions access %q (valid: read-only, full)", p.Access) + } for _, preset := range p.Presets { if !preset.Valid() { return fmt.Errorf("invalid preset %q (valid: edit, bare)", preset) diff --git a/pkg/api/permissions_schema.go b/pkg/api/permissions_schema.go index fd75e904..1208c74c 100644 --- a/pkg/api/permissions_schema.go +++ b/pkg/api/permissions_schema.go @@ -37,6 +37,17 @@ func (PermissionMode) JSONSchema() *jsonschema.Schema { } } +// JSONSchema declares the portable access levels. +func (AccessLevel) JSONSchema() *jsonschema.Schema { + return &jsonschema.Schema{ + Type: "string", + Enum: enumValues(AllAccessLevels()), + Description: "Portable access contract, compiled to each runtime's native dialect. read-only: the agent may read the workspace " + + "but cannot create, modify or delete files, spawn sub-agents, use third-party MCP servers, or obtain write access by approval. " + + "full: no access restriction, overriding a read-only intent from an earlier layer. Unset leaves every runtime unchanged.", + } +} + // JSONSchema declares the per-tool policy values. func (ToolPolicy) JSONSchema() *jsonschema.Schema { return &jsonschema.Schema{ diff --git a/pkg/api/registry/model.go b/pkg/api/registry/model.go index e5ea701d..4e7fa6ea 100644 --- a/pkg/api/registry/model.go +++ b/pkg/api/registry/model.go @@ -352,22 +352,41 @@ func (m Model) candidates() []Model { } // substituteModel picks a stand-in for a chain the user disabled entirely: the -// catalog's top preferred model on an enabled runtime, favouring the original's -// own provider family before crossing to another one. The per-request knobs are -// carried over, with the effort re-resolved against the substitute's own catalog -// entry so an unsupported tier does not travel with it. +// catalog's top preferred model on an enabled runtime. It keeps the original's +// runtime first, since switching mode changes what the run can do (an agent +// moved to the API loses its tools), then its provider, then crosses providers; +// on each runtime it prefers the original's model family. The per-request knobs +// are carried over, with the effort re-resolved against the substitute's own +// catalog entry so an unsupported tier does not travel with it. func substituteModel(m Model, disabled DisabledSet) (Model, bool) { - family := modelProvider(m) + provider := modelProvider(m) + var family string + if m.Provider != nil { + if known, ok := m.Provider.Lookup(m.Name); ok { + family = known.Family + } + } + rank := func(runtime Runtime) int { + switch { + case runtime.Provider == provider && runtime.Mode == m.Mode: + return 0 + case runtime.Provider == provider: + return 1 + default: + return 2 + } + } runtimes := AllRuntimes() - sort.SliceStable(runtimes, func(i, j int) bool { - return runtimes[i].Provider == family && runtimes[j].Provider != family - }) + sort.SliceStable(runtimes, func(i, j int) bool { return rank(runtimes[i]) < rank(runtimes[j]) }) for _, runtime := range runtimes { p, ok := runtime.ModelProvider() if !ok || disabled.Runtime(p, runtime.Mode) { continue } - pick, ok := p.latestModel(runtime.Mode, "") + pick, ok := p.latestModel(runtime.Mode, family) + if !ok { + pick, ok = p.latestModel(runtime.Mode, "") + } if !ok { continue } diff --git a/pkg/api/registry/model_disabled_ginkgo_test.go b/pkg/api/registry/model_disabled_ginkgo_test.go index 6c5cc938..b7ae655a 100644 --- a/pkg/api/registry/model_disabled_ginkgo_test.go +++ b/pkg/api/registry/model_disabled_ginkgo_test.go @@ -58,6 +58,27 @@ var _ = Describe("fallback chains under an opt-out set", func() { Expect(got[0].Name).NotTo(BeEmpty()) }) + DescribeTable("substitutes a disabled model on its authored runtime before widening", + func(mode RuntimeMode, disabledModels []string, family string) { + install(NewDisabledSet(nil, nil, nil, disabledModels, nil)) + resolved, err := ResolveModel(Model{Name: "claude-sonnet-5", Mode: mode}) + Expect(err).NotTo(HaveOccurred()) + + got := resolved.Candidates() + + Expect(got).To(HaveLen(1)) + Expect(got[0].Provider).To(Equal(Anthropic)) + Expect(got[0].Mode).To(Equal(mode)) + known, ok := Anthropic.Lookup(got[0].Name) + Expect(ok).To(BeTrue(), got[0].Name) + Expect(known.Family).To(Equal(family), got[0].Name) + Expect(disabledModels).NotTo(ContainElement("anthropic/" + got[0].Name)) + }, + Entry("agent keeps the family", ModeAgent, []string{"anthropic/claude-sonnet-5"}, "sonnet"), + Entry("cli keeps the family", ModeCLI, []string{"anthropic/claude-sonnet-5"}, "sonnet"), + Entry("agent moves to another family when the whole family is disabled", ModeAgent, sonnetModels(), "opus"), + ) + It("returns the unfiltered chain when every provider is disabled, so the caller reports the dead end", func() { providers := make([]string, 0, len(Providers())) for _, p := range Providers() { @@ -82,3 +103,13 @@ var _ = Describe("fallback chains under an opt-out set", func() { Expect(names(resolved.Candidates())).To(Equal([]string{"not-a-real-model-family"})) }) }) + +func sonnetModels() []string { + var out []string + for _, model := range Anthropic.Models() { + if model.Family == "sonnet" { + out = append(out, "anthropic/"+model.ID) + } + } + return out +} diff --git a/pkg/api/spec_codec.go b/pkg/api/spec_codec.go index 467d6399..d2592399 100644 --- a/pkg/api/spec_codec.go +++ b/pkg/api/spec_codec.go @@ -25,13 +25,6 @@ func (s Spec) MarshalYAML() (any, error) { if err != nil { return nil, err } - for path := range s.Fields() { - tokens := strings.Split(strings.TrimPrefix(path, "/"), "/") - value := serializedField(reflect.ValueOf(s), tokens) - if value.IsValid() && value.Type() == reflect.TypeOf(json.RawMessage(nil)) { - putWireField(fields, tokens, []byte(value.Interface().(json.RawMessage))) - } - } return yamlNumbers(fields) } diff --git a/pkg/api/spec_composition.go b/pkg/api/spec_composition.go index 8623363b..98574585 100644 --- a/pkg/api/spec_composition.go +++ b/pkg/api/spec_composition.go @@ -69,6 +69,10 @@ func ResolveSpecLayers(options ResolveSpecOptions) (ResolvedSpec, error) { } resolved := ResolvedSpec{Spec: composed.Spec, Trace: composed.Trace, Provenance: composed.Provenance, Warnings: composed.Warnings} + if resolved.Access, err = ResolveAccessState(composed.Trace); err != nil { + return ResolvedSpec{}, err + } + resolved.Spec.Permissions.AccessState = resolved.Access if err := resolved.Spec.ValidateStructure(); err != nil { return ResolvedSpec{}, fmt.Errorf("effective spec: %w", err) } diff --git a/pkg/api/spec_defaults.go b/pkg/api/spec_defaults.go index b786a76c..a3caaa2b 100644 --- a/pkg/api/spec_defaults.go +++ b/pkg/api/spec_defaults.go @@ -57,10 +57,6 @@ func (composed *ComposedSpec) applyDefaults(options ResolveSpecOptions) error { composed.Warnings = append(composed.Warnings, fmt.Sprintf("%s: %s; using the registry runtime default during the compatibility window", missing.Path, diagnostic.Error())) } composed.fillSavedSpec(saved) - if options.Saved != nil && !fieldCovered(composed.Spec.Fields(), "/budget/maxTokens") { - composed.Spec.Budget.MaxTokens = 4096 - composed.Provenance["/budget/maxTokens"] = FieldProvenance{Source: FieldSource{Kind: FieldSourceCatalog, Name: "Captain defaults", Key: "captain.defaults.maxTokens"}} - } if options.RequireModel && strings.TrimSpace(composed.Spec.Name) == "" { return &aiflags.UnconfiguredError{Field: "model", Model: composed.Spec.Name, Provider: composed.Spec.Provider} } diff --git a/pkg/api/spec_defaults_ginkgo_test.go b/pkg/api/spec_defaults_ginkgo_test.go index b175bd05..5930fad2 100644 --- a/pkg/api/spec_defaults_ginkgo_test.go +++ b/pkg/api/spec_defaults_ginkgo_test.go @@ -90,14 +90,14 @@ var _ = Describe("Saved spec defaults", func() { Expect(err).To(MatchError(ContainSubstring("sandbox mode"))) }) - It("uses catalog effort and the existing token default after saved gaps, preserving explicit clears", func() { + It("uses catalog effort after saved gaps, leaves max tokens to the runtime, and preserves explicit clears", func() { saved := captainconfig.AIDefaults{} layer := RequestSpecLayer("request", Spec{Model: Model{Name: "agent:fable"}}) result, err := ResolveSpecLayers(ResolveSpecOptions{Saved: &saved, Layers: []SpecLayer{layer}}) Expect(err).NotTo(HaveOccurred()) - Expect(result.Spec.Budget.MaxTokens).To(Equal(4096)) + Expect(result.Spec.Budget.MaxTokens).To(BeZero()) Expect(result.Spec.Effort).To(Equal(EffortHigh)) - Expect(result.Provenance["/budget/maxTokens"].Source.Kind).To(Equal(FieldSourceCatalog)) + Expect(result.Provenance).NotTo(HaveKey("/budget/maxTokens")) Expect(result.Provenance["/effort"].Source.Kind).To(Equal(FieldSourceCatalog)) layer.Spec = layer.Spec.WithExplicit("/budget/maxTokens", "/effort") result, err = ResolveSpecLayers(ResolveSpecOptions{Saved: &saved, Layers: []SpecLayer{layer}}) diff --git a/pkg/api/spec_layers.go b/pkg/api/spec_layers.go index 8411c2c7..fe3ce18d 100644 --- a/pkg/api/spec_layers.go +++ b/pkg/api/spec_layers.go @@ -1,6 +1,7 @@ package api import ( + "cmp" "fmt" "slices" "strings" @@ -39,6 +40,7 @@ type SpecLayer struct { Name string `json:"name" yaml:"name"` Scope SpecLayerScope `json:"scope" yaml:"scope"` Spec Spec `json:"spec,omitempty" yaml:"spec,omitempty"` + Order int `json:"order,omitempty" yaml:"order,omitempty"` } // ResolvedSpec is Captain's effective runtime profile plus ordered provenance. @@ -47,6 +49,9 @@ type ResolvedSpec struct { Trace []SpecLayer `json:"trace" yaml:"trace"` Warnings []string `json:"warnings,omitempty" yaml:"warnings,omitempty"` Provenance map[string]FieldProvenance `json:"provenance,omitempty" yaml:"provenance,omitempty"` + // Access is the layer-resolved access intent and the layer that set it; see + // ResolveAccessState. The same state rides on Spec.Permissions.AccessState. + Access *AccessState `json:"access,omitempty" yaml:"access,omitempty"` } // PromptSpecLayer adapts parsed .prompt frontmatter into the normal surface layer. @@ -60,11 +65,14 @@ func RequestSpecLayer(name string, spec Spec) SpecLayer { return SpecLayer{Name: name, Source: SpecLayerSourceRequest, Scope: SpecLayerUser, Spec: spec} } -// OrderSpecLayers copies the stack into effective scope order, preserving ties. +// OrderSpecLayers sorts by explicit order, then scope, preserving selection order for ties. func OrderSpecLayers(input ...SpecLayer) []SpecLayer { layers := append([]SpecLayer(nil), input...) slices.SortStableFunc(layers, func(left, right SpecLayer) int { - return scopeRank(left.Scope) - scopeRank(right.Scope) + if order := cmp.Compare(left.Order, right.Order); order != 0 { + return order + } + return cmp.Compare(scopeRank(left.Scope), scopeRank(right.Scope)) }) return layers } diff --git a/pkg/api/spec_merge_differential_test.go b/pkg/api/spec_merge_differential_test.go index ef2432ef..9431897e 100644 --- a/pkg/api/spec_merge_differential_test.go +++ b/pkg/api/spec_merge_differential_test.go @@ -182,6 +182,13 @@ func legacyMergePermissions(p, o Permissions) Permissions { if o.ApprovalTimeout != "" { p.ApprovalTimeout = o.ApprovalTimeout } + // The access level layers like the mode: a layer that names one replaces it. + if o.Access != "" { + p.Access = o.Access + } + if o.AccessState != nil { + p.AccessState = o.AccessState + } if len(o.Presets) > 0 { p.Presets = o.Presets } diff --git a/pkg/api/spec_presence_ginkgo_test.go b/pkg/api/spec_presence_ginkgo_test.go index 0e1e62ad..e417db8c 100644 --- a/pkg/api/spec_presence_ginkgo_test.go +++ b/pkg/api/spec_presence_ginkgo_test.go @@ -28,6 +28,20 @@ var _ = Describe("Spec field presence", func() { Entry("YAML", yaml.Unmarshal, yaml.Marshal, "model: agent:sonnet\nnoCache: false\nfallbacks: []\nbudget: {cost: 0, maxTurns: 4}\nmemory: {skipSkills: false}\nprompt: review\n"), ) + DescribeTable("treats a null opaque prompt field as an explicit clear", func(decode func([]byte, any) error, data string) { + var override Spec + Expect(decode([]byte(data), &override)).To(Succeed()) + Expect(override.Prompt.TypeSafeQuestions).To(BeNil()) + Expect(override.Fields()).To(HaveKeyWithValue("/prompt/typeSafeQuestions", true)) + base := Spec{Prompt: Prompt{User: "review", OutputSchemaType: SchemaTypeTypeSafe, TypeSafeQuestions: json.RawMessage(`{"valid":{"type":"noul"}}`)}} + merged := base.Merge(override) + Expect(merged.Prompt.TypeSafeQuestions).To(BeNil()) + Expect(merged.Prompt.Validate()).To(Succeed()) + }, + Entry("JSON", json.Unmarshal, `{"prompt":{"outputSchemaType":"json-schema","typeSafeQuestions":null}}`), + Entry("YAML", yaml.Unmarshal, "prompt:\n outputSchemaType: json-schema\n typeSafeQuestions: null\n"), + ) + It("merges intentional zero values without losing sibling fields or mutating input", func() { base := Spec{Model: Model{Name: "sonnet", NoCache: true, Fallbacks: []Model{{Name: "sol"}}}, Budget: Budget{Cost: 2, MaxTurns: 4}, Memory: Memory{SkipSkills: true}} override := (Spec{}).WithExplicit("/noCache", "/fallbacks", "/budget/cost", "/memory/skipSkills") diff --git a/pkg/api/spec_runtime.go b/pkg/api/spec_runtime.go index 325d227c..3fe4c8cd 100644 --- a/pkg/api/spec_runtime.go +++ b/pkg/api/spec_runtime.go @@ -5,17 +5,27 @@ import "fmt" // ValidateRuntimeSpec checks an already-resolved primary and its fallbacks. // Unsupported permission/resource capabilities warn; malformed states, agent // tool-policy refusals, and unsupported sandbox isolation remain hard errors. +// +// Each candidate is checked as it will run: with its access intent compiled by +// CompileAccess for its own runtime, the same compilation the provider +// decorator applies, so a posture a fallback cannot reach is refused here +// rather than after the primary has failed. func ValidateRuntimeSpec(spec Spec) ([]string, error) { var warnings []string for index, model := range append([]Model{spec.Model}, spec.Fallbacks...) { - if _, _, err := model.Runtime(); err != nil { - return warnings, fmt.Errorf("model %q: %w", model.Name, err) - } - if err := RequireToolPolicySupport(model.Provider, model.Mode, spec.Permissions); err != nil { + p, mode, err := model.Runtime() + if err != nil { return warnings, fmt.Errorf("model %q: %w", model.Name, err) } candidate := spec candidate.Model = model + candidate, report, err := CompileAccess(RuntimeOf(p, mode), candidate) + if err != nil { + return warnings, fmt.Errorf("model %q: %w", model.Name, err) + } + if err := RequireToolPolicySupport(p, mode, candidate.Permissions); err != nil { + return warnings, fmt.Errorf("model %q: %w", model.Name, err) + } sandboxWarning, err := ValidateResolvedSandbox(candidate) if err != nil { return warnings, fmt.Errorf("model %q: %w", model.Name, err) @@ -24,6 +34,9 @@ func ValidateRuntimeSpec(spec Spec) ([]string, error) { if sandboxWarning != "" { candidateWarnings = append(candidateWarnings, sandboxWarning) } + for _, equivalence := range report.Equivalences { + candidateWarnings = append(candidateWarnings, "permissions.access read-only: "+equivalence) + } for _, warning := range candidateWarnings { if index > 0 { warning = fmt.Sprintf("fallback[%d] %q: %s", index-1, model.Name, warning) From 78a71cd2b7cc0fb773f98292cbd045e0cdad0820 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Thu, 22 Oct 2026 18:52:45 +0300 Subject: [PATCH 10/77] feat(ai): compile permissions.access read-only per runtime and record worktree workspaces Wrap every provider candidate, primary and fallbacks, in an access decorator so permissions.access read-only is compiled for the runtime that candidate actually runs on. A fallback in another family now receives its own dialect instead of the primary's. Explicitly supplied directories that are linked worktrees are recorded in the run workspace before the first turn, so active runs show their workspace while running. Detached HEAD is recorded as no branch. Active runs started before this change are reconciled without altering their execution state. Runtime presets gain a sort_order column and a Lint built-in preset is added. Config home resolution moves to captainconfig.Home. --- migrations/41_runtime_profiles.pg.hcl | 5 ++ pkg/ai/access.go | 62 +++++++++++++++++ pkg/ai/access_ginkgo_test.go | 69 +++++++++++++++++++ pkg/ai/agent/setup/setup.go | 8 +++ pkg/ai/agent/setup/workspace.go | 50 ++++++++++++++ pkg/ai/agent/setup/workspace_ginkgo_test.go | 41 +++++++++++ pkg/ai/agent/setup/worktree_state.go | 5 +- pkg/ai/client.go | 2 +- pkg/ai/provider/access_argv_ginkgo_test.go | 54 +++++++++++++++ pkg/ai/runtime_candidates_ginkgo_test.go | 24 +++++++ pkg/captainconfig/config.go | 14 ++++ pkg/database/runtime_profile_store.go | 11 +-- pkg/lint/promptfile/run_ginkgo_test.go | 10 +++ pkg/promptrun/record_completed.go | 2 +- pkg/promptrun/record_ginkgo_test.go | 22 ++++-- pkg/promptrun/recorder.go | 11 ++- pkg/promptrun/workspace.go | 46 +++++++++++++ pkg/promptrun/workspace_ginkgo_test.go | 57 +++++++++++++++ .../builtin_source_ginkgo_test.go | 9 +-- pkg/runtimeprofiles/db_source.go | 2 +- .../db_source_integration_test.go | 18 +++++ pkg/runtimeprofiles/default_catalog.go | 13 +--- .../default_catalog_ginkgo_test.go | 2 +- .../embedded_source_ginkgo_test.go | 4 +- 24 files changed, 506 insertions(+), 35 deletions(-) create mode 100644 pkg/ai/access.go create mode 100644 pkg/ai/access_ginkgo_test.go create mode 100644 pkg/ai/agent/setup/workspace.go create mode 100644 pkg/ai/agent/setup/workspace_ginkgo_test.go create mode 100644 pkg/ai/provider/access_argv_ginkgo_test.go create mode 100644 pkg/ai/runtime_candidates_ginkgo_test.go create mode 100644 pkg/promptrun/workspace.go create mode 100644 pkg/promptrun/workspace_ginkgo_test.go diff --git a/migrations/41_runtime_profiles.pg.hcl b/migrations/41_runtime_profiles.pg.hcl index 98aa21ae..81d0949a 100644 --- a/migrations/41_runtime_profiles.pg.hcl +++ b/migrations/41_runtime_profiles.pg.hcl @@ -34,6 +34,11 @@ table "captain_runtime_presets" { type = enum.captain_spec_layer_scope } # The complete task Spec (api.RuntimePresetSpec) as JSON. + column "sort_order" { + null = false + type = bigint + default = 0 + } column "spec" { null = false type = jsonb diff --git a/pkg/ai/access.go b/pkg/ai/access.go new file mode 100644 index 00000000..7c47625b --- /dev/null +++ b/pkg/ai/access.go @@ -0,0 +1,62 @@ +package ai + +import ( + "context" + + "github.com/flanksource/captain/pkg/api" + "github.com/flanksource/commons/logger" +) + +var accessLog = logger.GetLogger("ai") + +// accessProvider compiles the request's access intent for the runtime this +// candidate actually runs on. It wraps every candidate — the primary and each +// fallback — so a fallback in another family speaks its own dialect rather +// than the primary's. With no access intent the request passes through as is. +type accessProvider struct { + provider Provider +} + +func (p *accessProvider) GetModel() string { return p.provider.GetModel() } +func (p *accessProvider) GetRuntime() Runtime { return p.provider.GetRuntime() } +func (p *accessProvider) Unwrap() Provider { return p.provider } + +func (p *accessProvider) request(ctx context.Context, req Request) (Request, error) { + compiled, report, err := api.CompileAccess(p.GetRuntime(), req) + if err != nil { + return Request{}, err + } + for _, equivalence := range report.Equivalences { + LoggerFromContext(ctx, accessLog).Debugf("%s permissions.access read-only: %s", report.Runtime, equivalence) + } + return compiled, nil +} + +func (p *accessProvider) Execute(ctx context.Context, req Request) (*Response, error) { + req, err := p.request(ctx, req) + if err != nil { + return nil, err + } + return p.provider.Execute(ctx, req) +} + +type accessStreamingProvider struct { + *accessProvider + streamer StreamingProvider +} + +func (p *accessStreamingProvider) ExecuteStream(ctx context.Context, req Request) (<-chan Event, error) { + req, err := p.request(ctx, req) + if err != nil { + return nil, err + } + return p.streamer.ExecuteStream(ctx, req) +} + +func withAccess(provider Provider) Provider { + base := &accessProvider{provider: provider} + if streamer, ok := provider.(StreamingProvider); ok { + return &accessStreamingProvider{accessProvider: base, streamer: streamer} + } + return base +} diff --git a/pkg/ai/access_ginkgo_test.go b/pkg/ai/access_ginkgo_test.go new file mode 100644 index 00000000..aea68c16 --- /dev/null +++ b/pkg/ai/access_ginkgo_test.go @@ -0,0 +1,69 @@ +package ai + +import ( + "context" + "errors" + + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" + + "github.com/flanksource/captain/pkg/api" +) + +type accessCaptureProvider struct { + runtime Runtime + err error + request Request +} + +func (p *accessCaptureProvider) Execute(_ context.Context, req Request) (*Response, error) { + p.request = req + return &Response{}, p.err +} + +func (p *accessCaptureProvider) GetModel() string { return "capture" } +func (p *accessCaptureProvider) GetRuntime() Runtime { return p.runtime } + +var _ = Describe("access decorator", func() { + It("compiles read-only for each fallback candidate in its own dialect", func() { + claude := &accessCaptureProvider{runtime: RuntimeOf(Anthropic, ModeAgent), err: errors.New("anthropic: 429 rate limit")} + codex := &accessCaptureProvider{runtime: RuntimeOf(OpenAI, ModeAgent)} + byName := map[string]Provider{"sonnet": withAccess(claude), "gpt": withAccess(codex)} + fallback := &fallbackProvider{ + candidates: []api.Model{{Name: "sonnet"}, {Name: "gpt"}}, + build: func(cfg Config) (Provider, error) { return byName[cfg.Model.Name], nil }, + built: make([]Provider, 2), + } + req := Request{Permissions: api.Permissions{Access: api.AccessReadOnly}} + + _, err := fallback.Execute(context.Background(), req) + + Expect(err).NotTo(HaveOccurred()) + Expect(claude.request.Permissions.Tools.DenyList()).To(ContainElements("Bash", "Edit", "Write", "Agent")) + Expect(claude.request.Sandbox).To(BeNil()) + Expect(codex.request.Permissions.Tools).To(BeEmpty()) + Expect(codex.request.Sandbox.Policy.Filesystem.Access).To(Equal(api.SandboxFilesystemReadOnly)) + Expect(codex.request.Permissions.Mode).To(Equal(api.PermissionBypass)) + Expect(req.Permissions.Tools).To(BeNil(), "the caller's request is never written through") + }) + + It("passes a request without access through unchanged", func() { + capture := &accessCaptureProvider{runtime: RuntimeOf(OpenAI, ModeCLI)} + req := Request{Permissions: api.Permissions{Mode: api.PermissionPlan, Tools: api.Tools{"Read": api.ToolPolicyAllow}}} + + _, err := withAccess(capture).Execute(context.Background(), req) + + Expect(err).NotTo(HaveOccurred()) + Expect(capture.request).To(Equal(req)) + }) + + It("refuses a candidate that cannot reach read-only before it runs", func() { + capture := &accessCaptureProvider{runtime: RuntimeOf(OpenAI, ModeAgent)} + req := Request{Permissions: api.Permissions{Access: api.AccessReadOnly}, Sandbox: &api.SandboxRef{Mode: api.SandboxOff}} + + _, err := withAccess(capture).Execute(context.Background(), req) + + Expect(err).To(MatchError(ContainSubstring(`sandbox mode "off" cannot confine the agent`))) + Expect(capture.request).To(Equal(Request{})) + }) +}) diff --git a/pkg/ai/agent/setup/setup.go b/pkg/ai/agent/setup/setup.go index 55151be4..aee08119 100644 --- a/pkg/ai/agent/setup/setup.go +++ b/pkg/ai/agent/setup/setup.go @@ -179,6 +179,14 @@ func (p *Plugin) PreRun(hc *agent.HookContext) error { p.prepared = res hc.Workspace().Cwd = res.Cwd if !Relocates(checkout) { + workspace, err := InspectWorkspace(res.Cwd) + if err != nil { + return err + } + if workspace.Worktree != nil { + hc.Workspace().Worktree = workspace.Worktree + hc.Workspace().Repo = workspace.Worktree.Repo + } return nil } p.relocation = &relocation{kind: "checkout", path: res.Cwd} diff --git a/pkg/ai/agent/setup/workspace.go b/pkg/ai/agent/setup/workspace.go new file mode 100644 index 00000000..ae713cce --- /dev/null +++ b/pkg/ai/agent/setup/workspace.go @@ -0,0 +1,50 @@ +package setup + +import ( + "fmt" + "os" + "path/filepath" + + "github.com/flanksource/captain/pkg/api" +) + +// InspectWorkspace records an explicitly supplied directory and its linked worktree. +func InspectWorkspace(cwd string) (*api.WorkspaceRecord, error) { + if _, err := os.Stat(cwd); err != nil { + return nil, fmt.Errorf("inspect workspace %s: %w", cwd, err) + } + workspace := &api.WorkspaceRecord{Cwd: cwd} + path, err := filepath.Abs(cwd) + if err != nil { + return nil, err + } + for { + marker, err := os.Stat(filepath.Join(path, ".git")) + if err == nil { + if marker.IsDir() { + return workspace, nil + } + gitDir, err := git(path, "rev-parse", "--absolute-git-dir") + if err != nil { + return nil, err + } + commonDir, err := git(path, "rev-parse", "--path-format=absolute", "--git-common-dir") + if err != nil { + return nil, err + } + if gitDir == commonDir { + return workspace, nil + } + workspace.Worktree, err = recordWorktree(path, false) + return workspace, err + } + if !os.IsNotExist(err) { + return nil, fmt.Errorf("inspect workspace %s: %w", cwd, err) + } + parent := filepath.Dir(path) + if parent == path { + return workspace, nil + } + path = parent + } +} diff --git a/pkg/ai/agent/setup/workspace_ginkgo_test.go b/pkg/ai/agent/setup/workspace_ginkgo_test.go new file mode 100644 index 00000000..e9596045 --- /dev/null +++ b/pkg/ai/agent/setup/workspace_ginkgo_test.go @@ -0,0 +1,41 @@ +package setup_test + +import ( + "path/filepath" + + "github.com/flanksource/captain/pkg/ai" + "github.com/flanksource/captain/pkg/ai/agent" + "github.com/flanksource/captain/pkg/ai/agent/setup" + "github.com/flanksource/captain/pkg/api" + "github.com/flanksource/commons-db/shell" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("specified workspaces", func() { + It("records a linked worktree supplied as the execution directory without owning its cleanup", func() { + repo := sourceRepo() + path := filepath.Join(GinkgoT().TempDir(), "specified") + gitIn(repo, "worktree", "add", "-b", "feature/specified", path) + DeferCleanup(func() { gitIn(repo, "worktree", "remove", "--force", path) }) + path, err := filepath.EvalSymlinks(path) + Expect(err).NotTo(HaveOccurred()) + base := gitIn(path, "rev-parse", "HEAD") + plugin := &setup.Plugin{} + hc := &agent.HookContext{Request: &ai.Request{Setup: &shell.Setup{Cwd: path}}, Response: &ai.Response{}} + Expect(plugin.PreRun(hc)).To(Succeed()) + Expect(hc.Workspace().Worktree).To(Equal(&api.WorktreeState{ + Repo: repo, Path: path, Branch: "feature/specified", Base: base, Setup: base, + })) + Expect(plugin.Post(hc, agent.PhaseRun)).To(Succeed()) + Expect(path).To(BeADirectory()) + }) + + It("does not mark a primary checkout or a non-Git directory as an isolated worktree", func() { + for _, path := range []string{sourceRepo(), GinkgoT().TempDir()} { + workspace, err := setup.InspectWorkspace(path) + Expect(err).NotTo(HaveOccurred()) + Expect(workspace).To(Equal(&api.WorkspaceRecord{Cwd: path})) + } + }) +}) diff --git a/pkg/ai/agent/setup/worktree_state.go b/pkg/ai/agent/setup/worktree_state.go index a38b9966..f84d0122 100644 --- a/pkg/ai/agent/setup/worktree_state.go +++ b/pkg/ai/agent/setup/worktree_state.go @@ -87,9 +87,12 @@ func recordWorktree(path string, snapshot bool) (*api.WorktreeState, error) { // `git worktree list` — rather than the checkout's path, which a remote checkout // does not have. func inspectWorktree(dir string) (branch, repo string, err error) { - if branch, err = git(dir, "symbolic-ref", "--short", "HEAD"); err != nil { + if branch, err = git(dir, "rev-parse", "--abbrev-ref", "HEAD"); err != nil { return "", "", err } + if branch == "HEAD" { + branch = "" + } list, err := git(dir, "worktree", "list", "--porcelain") if err != nil { return "", "", err diff --git a/pkg/ai/client.go b/pkg/ai/client.go index eeee1a18..5c02fc0a 100644 --- a/pkg/ai/client.go +++ b/pkg/ai/client.go @@ -48,7 +48,7 @@ func newResolvedProvider(cfg Config) (Provider, error) { if err != nil { return nil, err } - return withModelErrorRecommendations(withEffortValidation(p, cfg.Model.Effort)), nil + return withModelErrorRecommendations(withAccess(withEffortValidation(p, cfg.Model.Effort))), nil } // suggestModelName appends the closest catalog model ids to an unresolvable-model diff --git a/pkg/ai/provider/access_argv_ginkgo_test.go b/pkg/ai/provider/access_argv_ginkgo_test.go new file mode 100644 index 00000000..8b231510 --- /dev/null +++ b/pkg/ai/provider/access_argv_ginkgo_test.go @@ -0,0 +1,54 @@ +package provider + +import ( + "strings" + + "github.com/flanksource/captain/pkg/ai" + "github.com/flanksource/captain/pkg/api" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +// compiledReadOnly is the request a provider receives once the access +// decorator has compiled permissions.access for its runtime. +func compiledReadOnly(runtime api.Runtime) ai.Request { + req := ai.Request{Prompt: api.Prompt{User: "review"}, Permissions: api.Permissions{Access: api.AccessReadOnly}} + compiled, _, err := api.CompileAccess(runtime, req) + Expect(err).NotTo(HaveOccurred()) + return compiled +} + +var _ = Describe("permissions.access read-only on the wire", func() { + It("runs codex-cli read-only with approval never and no MCP servers", func() { + args, cleanup, err := buildCodexCLIArgs(codexCLIConfig{Model: "gpt-5.5"}, compiledReadOnly(api.RuntimeOf(api.OpenAI, api.ModeCLI))) + Expect(err).NotTo(HaveOccurred()) + DeferCleanup(cleanup) + + Expect(sandboxFlagValue(args, "--sandbox")).To(Equal("read-only")) + Expect(args).To(ContainElement(`approval_policy="never"`)) + Expect(strings.Join(args, " ")).To(ContainSubstring("mcp_servers")) + }) + + It("starts codex app-server threads and turns read-only with approval never", func() { + req := compiledReadOnly(api.RuntimeOf(api.OpenAI, api.ModeAgent)) + thread, err := buildThreadStartParams("gpt-5.5", req, nil) + Expect(err).NotTo(HaveOccurred()) + turn, err := buildTurnStartParams("gpt-5.5", req, "thread-1", nil) + Expect(err).NotTo(HaveOccurred()) + + Expect(thread).To(HaveKeyWithValue("approvalPolicy", "never")) + Expect(thread).To(HaveKeyWithValue("sandbox", "read-only")) + Expect(turn).To(HaveKeyWithValue("approvalPolicy", "never")) + Expect(turn["sandboxPolicy"]).To(HaveKeyWithValue("type", "readOnly")) + }) + + It("denies claude's write, shell and sub-agent tools with strict MCP", func() { + args, cleanup, err := buildClaudeCLIArgs("claude-sonnet-5", compiledReadOnly(api.RuntimeOf(api.Anthropic, api.ModeCLI))) + Expect(err).NotTo(HaveOccurred()) + DeferCleanup(cleanup) + + denied := strings.Split(sandboxFlagValue(args, "--disallowedTools"), ",") + Expect(denied).To(ContainElements("Agent", "Bash", "Edit", "MultiEdit", "NotebookEdit", "Task", "Workflow", "Write")) + Expect(args).To(ContainElement("--strict-mcp-config")) + }) +}) diff --git a/pkg/ai/runtime_candidates_ginkgo_test.go b/pkg/ai/runtime_candidates_ginkgo_test.go new file mode 100644 index 00000000..75cde3a8 --- /dev/null +++ b/pkg/ai/runtime_candidates_ginkgo_test.go @@ -0,0 +1,24 @@ +package ai + +import ( + "github.com/flanksource/captain/pkg/api" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("Runtime candidates", func() { + DescribeTable("keep the authored agent runtime and exact model", + func(model api.Model, name string) { + candidates, err := ResolveCandidates(model) + Expect(err).NotTo(HaveOccurred()) + Expect(candidates).To(HaveExactElements(SatisfyAll( + HaveField("Name", name), + HaveField("Provider", api.Anthropic), + HaveField("Mode", api.ModeAgent), + ))) + }, + Entry("selector with exact id", api.Model{Name: "agent:claude-sonnet-5"}, "claude-sonnet-5"), + Entry("frontmatter model and mode", api.Model{Name: "claude-sonnet-5", Mode: api.ModeAgent}, "claude-sonnet-5"), + Entry("selector with alias", api.Model{Name: "agent:sonnet"}, "claude-sonnet-5-5"), + ) +}) diff --git a/pkg/captainconfig/config.go b/pkg/captainconfig/config.go index c501ac48..0ae82698 100644 --- a/pkg/captainconfig/config.go +++ b/pkg/captainconfig/config.go @@ -302,6 +302,20 @@ func Path() (string, error) { return filepath.Join(home, ".captain.yaml"), nil } +// Home returns Captain's user configuration directory, which holds implicit +// record directories such as presets, profiles and prompts: +// $XDG_CONFIG_HOME/captain, or ~/.config/captain. +func Home() (string, error) { + if base := os.Getenv("XDG_CONFIG_HOME"); base != "" { + return filepath.Join(base, "captain"), nil + } + home, err := os.UserHomeDir() + if err != nil { + return "", fmt.Errorf("resolve home directory: %w", err) + } + return filepath.Join(home, ".config", "captain"), nil +} + // Load reads the config file. The bool return is false when the file does // not exist (a normal first-run state), in which case err is nil and the // returned Config is zero-valued. diff --git a/pkg/database/runtime_profile_store.go b/pkg/database/runtime_profile_store.go index 66127657..674be38f 100644 --- a/pkg/database/runtime_profile_store.go +++ b/pkg/database/runtime_profile_store.go @@ -37,6 +37,7 @@ type runtimePresetRecord struct { Presets []string `gorm:"column:presets;serializer:json;type:jsonb"` CreatedAt time.Time `gorm:"column:created_at"` UpdatedAt time.Time `gorm:"column:updated_at"` + Order int `gorm:"column:sort_order"` } func (runtimePresetRecord) TableName() string { return "captain_runtime_presets" } @@ -51,6 +52,7 @@ type RuntimePreset struct { Presets []string `json:"presets"` CreatedAt time.Time `json:"createdAt"` UpdatedAt time.Time `json:"updatedAt"` + Order int `json:"order,omitempty" yaml:"order,omitempty"` } // RuntimePresetInput is everything a caller authors; ids and timestamps are @@ -61,6 +63,7 @@ type RuntimePresetInput struct { Scope api.SpecLayerScope Spec api.RuntimePresetSpec Presets []string + Order int } // ListRuntimePresets returns every preset ordered by name, always as a slice so @@ -136,7 +139,7 @@ func (db *DB) UpdateRuntimePreset(ctx context.Context, id uuid.UUID, input Runti return nil, fmt.Errorf("encode captain runtime preset references: %w", err) } result := db.gorm.WithContext(ctx).Model(&runtimePresetRecord{}).Where("id = ?", id).Updates(map[string]any{ - "name": record.Name, "description": record.Description, "scope": record.Scope, + "name": record.Name, "description": record.Description, "scope": record.Scope, "sort_order": record.Order, "spec": gorm.Expr("?::jsonb", string(spec)), "presets": gorm.Expr("?::jsonb", string(presets)), "updated_at": clause.Expr{SQL: "now()"}, }) @@ -177,13 +180,13 @@ func runtimePresetRecordFrom(id uuid.UUID, input RuntimePresetInput) (runtimePre if input.Presets == nil { input.Presets = []string{} } - preset := api.RuntimePreset{ID: id.String(), Name: input.Name, Scope: input.Scope, Spec: input.Spec, Presets: input.Presets} + preset := api.RuntimePreset{ID: id.String(), Name: input.Name, Scope: input.Scope, Spec: input.Spec, Presets: input.Presets, Order: input.Order} if err := api.ValidateRuntimePreset(preset); err != nil { return runtimePresetRecord{}, fmt.Errorf("%w: %v", ErrRuntimeInvalid, err) } return runtimePresetRecord{ ID: id, Name: input.Name, Description: nullableTrimmed(input.Description), - Scope: input.Scope, Spec: input.Spec, Presets: input.Presets, + Scope: input.Scope, Spec: input.Spec, Presets: input.Presets, Order: input.Order, }, nil } @@ -197,6 +200,6 @@ func runtimeWriteError(action, name string, err error) error { func (r runtimePresetRecord) toPreset() RuntimePreset { return RuntimePreset{ ID: r.ID, Name: r.Name, Description: optionalString(r.Description), Scope: r.Scope, - Spec: r.Spec, Presets: r.Presets, CreatedAt: r.CreatedAt, UpdatedAt: r.UpdatedAt, + Spec: r.Spec, Presets: r.Presets, CreatedAt: r.CreatedAt, UpdatedAt: r.UpdatedAt, Order: r.Order, } } diff --git a/pkg/lint/promptfile/run_ginkgo_test.go b/pkg/lint/promptfile/run_ginkgo_test.go index 26f7f58b..7f1b8e88 100644 --- a/pkg/lint/promptfile/run_ginkgo_test.go +++ b/pkg/lint/promptfile/run_ginkgo_test.go @@ -94,6 +94,16 @@ var _ = Describe("Promptfile linter", func() { Expect(results[0].Success).To(BeTrue()) }) + It("accepts the built-in prompts", func() { + builtin, err := filepath.Abs(filepath.Join("..", "..", "ai", "prompt", "builtin")) + Expect(err).NotTo(HaveOccurred()) + results := Run(context.Background(), Options{WorkDir: builtin, Data: map[string]any{"files": "docs/spec.md"}}) + Expect(results).To(HaveLen(1)) + Expect(results[0].Success).To(BeTrue(), results[0].Error) + Expect(results[0].FileCount).To(Equal(5)) + Expect(results[0].Violations).To(BeEmpty()) + }) + It("honors cancellation", func() { write(filepath.Join(directory, "review.prompt"), "Review.\n") ctx, cancel := context.WithCancel(context.Background()) diff --git a/pkg/promptrun/record_completed.go b/pkg/promptrun/record_completed.go index c3ea7e5b..41dbbb03 100644 --- a/pkg/promptrun/record_completed.go +++ b/pkg/promptrun/record_completed.go @@ -38,6 +38,6 @@ func RecordCompleted(ctx context.Context, rec *Recording, done Completed) (uuid. r := newRecorder(ctx, rec, run) r.prepare(done.Runtime, api.Model{Name: done.Model}, done.Resolved.Spec, done.ProviderSessionID) spec := done.Resolved.Spec - startErr := r.Start(&spec) + startErr := r.Start(&spec, nil) return run.ID, errors.Join(startErr, r.settle(done.Outcome, done.Iterations, done.Notices, nil)) } diff --git a/pkg/promptrun/record_ginkgo_test.go b/pkg/promptrun/record_ginkgo_test.go index 2730ad0e..ca865d73 100644 --- a/pkg/promptrun/record_ginkgo_test.go +++ b/pkg/promptrun/record_ginkgo_test.go @@ -26,6 +26,7 @@ type eventsProvider struct { calls int events []ai.Event block bool + before func() } func (p *eventsProvider) GetModel() string { return "claude-sonnet-5" } @@ -36,6 +37,9 @@ func (p *eventsProvider) Execute(context.Context, ai.Request) (*ai.Response, err return nil, errors.New("eventsProvider only streams") } func (p *eventsProvider) ExecuteStream(ctx context.Context, _ ai.Request) (<-chan ai.Event, error) { + if p.before != nil { + p.before() + } p.mu.Lock() p.calls++ p.mu.Unlock() @@ -375,7 +379,7 @@ var _ = Describe("a recorded prompt run", func() { Expect(messages).To(HaveLen(len(res.Response.Workspace.Notices))) }) - It("persists the run workspace on finish", func(ctx SpecContext) { + It("persists the run workspace before the first turn and on finish", func(ctx SpecContext) { worktree := &api.WorktreeState{ Repo: cwd, Path: cwd + "/worktrees/shell-abc", Branch: "shell/abc", Base: "1111111111111111111111111111111111111111", Setup: "2222222222222222222222222222222222222222", @@ -384,13 +388,21 @@ var _ = Describe("a recorded prompt run", func() { commit := api.CommitRecord{SHA: worktree.Head, Message: "feat: fix the build"} hook := &workspaceHook{worktree: worktree, commit: commit} + rec := recording(nil) + rec.PromptRunID = uuid.New() + want := &api.WorkspaceRecord{Cwd: cwd, Worktree: worktree, Commits: []api.CommitRecord{commit}} + provider := &eventsProvider{events: answeredTurn(uuid.NewString()), before: func() { + running, err := db.GetPromptRun(ctx, rec.PromptRunID) + Expect(err).NotTo(HaveOccurred()) + Expect(running.State).To(Equal(database.PromptRunStateRunning)) + Expect(running.Workspace).To(Equal(want), "the workspace is visible before the first provider turn") + }} res, err := promptrun.Run(ctx, promptrun.Input{ - Resolved: resolved, Provider: &eventsProvider{events: answeredTurn(uuid.NewString())}, - Timeout: testTimeout, Record: recording(nil), Hooks: []any{hook}, + Resolved: resolved, Provider: provider, + Timeout: testTimeout, Record: rec, Hooks: []any{hook}, }) Expect(err).NotTo(HaveOccurred()) - want := &api.WorkspaceRecord{Cwd: cwd, Worktree: worktree, Commits: []api.CommitRecord{commit}} run, err := db.GetPromptRun(ctx, res.PromptRunID) Expect(err).NotTo(HaveOccurred()) Expect(run.Workspace).To(Equal(want), "notices, diff and metadata stay off the durable record") @@ -458,7 +470,7 @@ var _ = Describe("a recorded prompt run", func() { recorder := promptrun.Track(ctx, rec, admitted, api.RuntimeOf(api.Anthropic, api.ModeAgent), resolved.Spec.Model, resolved.Spec, "") spec := resolved.Spec - Expect(recorder.Start(&spec)).To(Succeed()) + Expect(recorder.Start(&spec, nil)).To(Succeed()) run, err := db.GetPromptRun(ctx, admitted.ID) Expect(err).NotTo(HaveOccurred()) Expect(run.State).To(Equal(database.PromptRunStateRunning)) diff --git a/pkg/promptrun/recorder.go b/pkg/promptrun/recorder.go index 75ad74b1..2e1cf914 100644 --- a/pkg/promptrun/recorder.go +++ b/pkg/promptrun/recorder.go @@ -121,7 +121,7 @@ func (r *Recorder) transcribeAPIRun() { // Start marks the run running with the spec that actually runs — the one setup // already transformed — and the runtime it resolved to, then binds a provider // session known up front. -func (r *Recorder) Start(spec *api.Spec) error { +func (r *Recorder) Start(spec *api.Spec, workspace *api.Workspace) error { r.mu.Lock() defer r.mu.Unlock() rendered, err := SpecDocument(*spec) @@ -131,7 +131,10 @@ func (r *Recorder) Start(spec *api.Spec) error { run, err := r.updateRun(func(run *database.PromptRun) (database.UpdatePromptRunInput, bool) { state, phase := database.PromptRunStateRunning, r.activePhase() runtime := r.resolvedRuntime(run.Runtime, spec) - update := database.UpdatePromptRunInput{State: &state, Phase: &phase, Runtime: &runtime, RenderedSpec: &rendered} + update := database.UpdatePromptRunInput{ + State: &state, Phase: &phase, Runtime: &runtime, RenderedSpec: &rendered, + Workspace: api.NewWorkspaceRecord(workspace), + } if len(r.offered) > 0 { update.Metadata = &map[string]any{"callerTools": r.offered} } @@ -464,7 +467,9 @@ type recordHook struct{ recorder *Recorder } func (h *recordHook) Name() string { return "promptrun-recorder" } -func (h *recordHook) PreRun(hc *agent.HookContext) error { return h.recorder.Start(hc.Request) } +func (h *recordHook) PreRun(hc *agent.HookContext) error { + return h.recorder.Start(hc.Request, hc.Workspace()) +} func firstNonEmpty(values ...string) string { for _, value := range values { diff --git a/pkg/promptrun/workspace.go b/pkg/promptrun/workspace.go new file mode 100644 index 00000000..a45ae503 --- /dev/null +++ b/pkg/promptrun/workspace.go @@ -0,0 +1,46 @@ +package promptrun + +import ( + "context" + "encoding/json" + "fmt" + + "github.com/flanksource/captain/pkg/ai/agent/setup" + "github.com/flanksource/captain/pkg/api" + "github.com/flanksource/captain/pkg/database" +) + +// ReconcileWorkspace records the workspace of an active run started before setup +// recorded it. It changes no execution or outcome state. +func ReconcileWorkspace(ctx context.Context, db *database.DB, run *database.PromptRun) error { + if run.Workspace != nil || (run.State != database.PromptRunStateRunning && run.State != database.PromptRunStateWaiting) { + return nil + } + raw, err := json.Marshal(run.RenderedSpec) + if err != nil { + return fmt.Errorf("encode run %s spec: %w", run.ID, err) + } + var spec api.Spec + if err := json.Unmarshal(raw, &spec); err != nil { + return fmt.Errorf("decode run %s spec: %w", run.ID, err) + } + if spec.Cwd() == "" { + return nil + } + workspace, err := setup.InspectWorkspace(spec.Cwd()) + if err != nil { + return fmt.Errorf("reconcile run %s workspace: %w", run.ID, err) + } + if workspace.Worktree != nil { + workspace.Worktree.Head = workspace.Worktree.Setup + workspace.Worktree.Base, workspace.Worktree.Setup = "", "" + } + updated, err := updateRun(ctx, db, run.ID, func(current *database.PromptRun) (database.UpdatePromptRunInput, bool) { + return database.UpdatePromptRunInput{Workspace: workspace}, current.Workspace == nil && !finishedRun(current.State) + }) + if err != nil { + return fmt.Errorf("record run %s workspace: %w", run.ID, err) + } + run.Workspace, run.Version = updated.Workspace, updated.Version + return nil +} diff --git a/pkg/promptrun/workspace_ginkgo_test.go b/pkg/promptrun/workspace_ginkgo_test.go new file mode 100644 index 00000000..1c28da4c --- /dev/null +++ b/pkg/promptrun/workspace_ginkgo_test.go @@ -0,0 +1,57 @@ +package promptrun_test + +import ( + "os" + "os/exec" + "path/filepath" + + "github.com/flanksource/captain/pkg/database" + "github.com/flanksource/captain/pkg/promptrun" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("active run workspace reconciliation", func() { + It("records an existing linked worktree without changing execution, staged files, or inventing the setup revision", func(ctx SpecContext) { + db := openRecordDB() + repo := GinkgoT().TempDir() + path := filepath.Join(GinkgoT().TempDir(), "active") + git := func(dir string, args ...string) string { + GinkgoHelper() + command := exec.Command("git", args...) + command.Dir = dir + out, err := command.CombinedOutput() + Expect(err).NotTo(HaveOccurred(), "%s", out) + return string(out) + } + git(repo, "init", "-q", "-b", "main", "--template=") + git(repo, "-c", "user.name=Test", "-c", "user.email=test@example.com", "-c", "commit.gpgsign=false", "commit", "--allow-empty", "-qm", "chore: seed") + git(repo, "worktree", "add", "-b", "feature/active", path) + DeferCleanup(func() { git(repo, "worktree", "remove", "--force", path) }) + Expect(os.WriteFile(filepath.Join(path, "change.txt"), []byte("work in progress\n"), 0o600)).To(Succeed()) + git(path, "add", "change.txt") + before := git(path, "status", "--porcelain") + session, err := db.CreateOrGetSession(ctx, hostTree()[0]) + Expect(err).NotTo(HaveOccurred()) + run, err := db.CreatePromptRun(ctx, database.CreatePromptRunInput{ + SessionID: session.ID, RenderedSpec: map[string]any{"setup": map[string]any{"cwd": path}}, + }) + Expect(err).NotTo(HaveOccurred()) + state := database.PromptRunStateRunning + run, err = db.UpdatePromptRun(ctx, database.UpdatePromptRunInput{ID: run.ID, ExpectedVersion: run.Version, State: &state}) + Expect(err).NotTo(HaveOccurred()) + Expect(promptrun.ReconcileWorkspace(ctx, db, run)).To(Succeed()) + Expect(run.Workspace.Worktree.Branch).To(Equal("feature/active")) + Expect(run.Workspace.Worktree.Setup).To(BeEmpty()) + Expect(run.Workspace.Worktree.Base).To(BeEmpty()) + Expect(run.Workspace.Worktree.Head).NotTo(BeEmpty()) + stored, err := db.GetPromptRun(ctx, run.ID) + Expect(err).NotTo(HaveOccurred()) + Expect(stored.Workspace).To(Equal(run.Workspace)) + Expect(stored.State).To(Equal(state)) + version := run.Version + Expect(promptrun.ReconcileWorkspace(ctx, db, run)).To(Succeed()) + Expect(run.Version).To(Equal(version)) + Expect(git(path, "status", "--porcelain")).To(Equal(before)) + }) +}) diff --git a/pkg/runtimeprofiles/builtin_source_ginkgo_test.go b/pkg/runtimeprofiles/builtin_source_ginkgo_test.go index 9fd8be4a..ebae7991 100644 --- a/pkg/runtimeprofiles/builtin_source_ginkgo_test.go +++ b/pkg/runtimeprofiles/builtin_source_ginkgo_test.go @@ -54,7 +54,7 @@ var _ = Describe("Built-in source", func() { Expect(NewBuiltinSource().Profiles()).To(BeNil()) }) - It("ships Edit, Plan and Read-only as context presets with their permission postures", func(ctx SpecContext) { + It("ships lint output and permission presets", func(ctx SpecContext) { presets, err := NewBuiltinSource().Presets().List(ctx) Expect(err).NotTo(HaveOccurred()) type posture struct { @@ -73,6 +73,7 @@ var _ = Describe("Built-in source", func() { } Expect(actual).To(Equal([]posture{ {Key: "edit", Name: "Edit", Scope: api.SpecLayerContext, Mode: api.PermissionAcceptEdits, Presets: []api.Preset{api.PresetEdit}}, + {Key: "lint", Name: "Lint", Scope: api.SpecLayerSurface}, {Key: "plan", Name: "Plan", Scope: api.SpecLayerContext, Mode: api.PermissionPlan, Tools: api.Tools{ "read": api.ToolPolicyAllow, "shell": api.ToolPolicyDeny, }}, @@ -120,7 +121,7 @@ var _ = Describe("Catalog built-in overrides", func() { listed, err := f.catalog.ListPresets(ctx) Expect(err).NotTo(HaveOccurred()) Expect(presetSummaries(listed)).To(Equal([][2]string{ - {"db", org.Name}, {"builtin", "Edit"}, {"builtin", "Plan"}, {"builtin", "Read-only"}, + {"db", org.Name}, {"builtin", "Edit"}, {"builtin", "Lint"}, {"builtin", "Plan"}, {"builtin", "Read-only"}, })) plan, err := f.catalog.GetPreset(ctx, "Plan") Expect(err).NotTo(HaveOccurred()) @@ -135,7 +136,7 @@ var _ = Describe("Catalog built-in overrides", func() { listed, err := f.catalog.ListPresets(ctx) Expect(err).NotTo(HaveOccurred()) Expect(presetSummaries(listed)).To(Equal([][2]string{ - {"file", "plan"}, {"builtin", "Edit"}, {"builtin", "Read-only"}, + {"file", "plan"}, {"builtin", "Edit"}, {"builtin", "Lint"}, {"builtin", "Read-only"}, })) override := listed[0] Expect(f.catalog.GetPreset(ctx, "PLAN")).To(Equal(override)) @@ -157,7 +158,7 @@ var _ = Describe("Catalog built-in overrides", func() { listed, err := f.catalog.ListPresets(ctx) Expect(err).NotTo(HaveOccurred()) Expect(presetSummaries(listed)).To(Equal([][2]string{ - {"db", "Plan"}, {"builtin", "Edit"}, {"builtin", "Read-only"}, + {"db", "Plan"}, {"builtin", "Edit"}, {"builtin", "Lint"}, {"builtin", "Read-only"}, })) Expect(f.catalog.GetPreset(ctx, "plan")).To(Equal(override)) Expect(f.catalog.GetPreset(ctx, builtinPlanID)).To(Equal(override)) diff --git a/pkg/runtimeprofiles/db_source.go b/pkg/runtimeprofiles/db_source.go index 42fa34c3..b7eb1777 100644 --- a/pkg/runtimeprofiles/db_source.go +++ b/pkg/runtimeprofiles/db_source.go @@ -53,7 +53,7 @@ func (s *dbSource) preset(row database.RuntimePreset) Preset { key := row.ID.String() return Preset{ ID: EncodeID(KindPreset, s.info.ID, key), Key: key, Source: s.info, Name: row.Name, - Description: row.Description, Scope: row.Scope, Spec: row.Spec, Presets: row.Presets, UpdatedAt: row.UpdatedAt, + Description: row.Description, Scope: row.Scope, Spec: row.Spec, Presets: row.Presets, UpdatedAt: row.UpdatedAt, Order: row.Order, } } diff --git a/pkg/runtimeprofiles/db_source_integration_test.go b/pkg/runtimeprofiles/db_source_integration_test.go index 6e3a1b80..7ddea1cd 100644 --- a/pkg/runtimeprofiles/db_source_integration_test.go +++ b/pkg/runtimeprofiles/db_source_integration_test.go @@ -26,6 +26,24 @@ func sameDB(db *database.DB) func(context.Context) (*database.DB, error) { } var _ = Describe("Database source", func() { + It("round trips preset order through creation, resolution and an explicit zero update", func(ctx SpecContext) { + db := openRuntimeDB(ctx, "captain_runtimeprofiles_order") + source, err := NewDBSource(DBSourceOptions{Read: sameDB(db), Write: sameDB(db)}) + Expect(err).NotTo(HaveOccurred()) + created, err := source.Presets().Create(ctx, PresetInput{Name: "Ordered", Scope: api.SpecLayerContext, Order: 100}) + Expect(err).NotTo(HaveOccurred()) + Expect(source.Presets().Get(ctx, created.Key)).To(Equal(created)) + Expect(created.Order).To(Equal(100)) + catalog, err := NewCatalog(source) + Expect(err).NotTo(HaveOccurred()) + layers, err := catalog.PresetLayers(ctx, []string{created.ID}) + Expect(err).NotTo(HaveOccurred()) + Expect(layers.Layers[0].Order).To(Equal(100)) + updated, err := source.Presets().Update(ctx, created.Key, PresetInput{Name: "Ordered", Scope: api.SpecLayerContext, Order: 0}) + Expect(err).NotTo(HaveOccurred()) + Expect(updated.Order).To(BeZero()) + }) + It("requires a reader and is read-only without a writer", func(ctx SpecContext) { _, err := NewDBSource(DBSourceOptions{}) Expect(err).To(MatchError(ContainSubstring("Read opener"))) diff --git a/pkg/runtimeprofiles/default_catalog.go b/pkg/runtimeprofiles/default_catalog.go index 043dfbe4..be9cb8d7 100644 --- a/pkg/runtimeprofiles/default_catalog.go +++ b/pkg/runtimeprofiles/default_catalog.go @@ -80,7 +80,7 @@ func runtimeRecordDirs(options DefaultCatalogOptions) ([]FileSourceOptions, erro seen[key] = true dirs = append(dirs, FileSourceOptions{Kind: kind, Dir: path, Label: path, Implicit: implicit}) } - configHome, err := captainConfigHome() + configHome, err := captainconfig.Home() if err != nil { return nil, err } @@ -173,14 +173,3 @@ func resolveRuntimeDir(raw, base string) (string, error) { } return filepath.Clean(resolved), nil } - -func captainConfigHome() (string, error) { - if base := os.Getenv("XDG_CONFIG_HOME"); base != "" { - return filepath.Join(base, "captain"), nil - } - home, err := os.UserHomeDir() - if err != nil { - return "", err - } - return filepath.Join(home, ".config", "captain"), nil -} diff --git a/pkg/runtimeprofiles/default_catalog_ginkgo_test.go b/pkg/runtimeprofiles/default_catalog_ginkgo_test.go index b839218c..77509243 100644 --- a/pkg/runtimeprofiles/default_catalog_ginkgo_test.go +++ b/pkg/runtimeprofiles/default_catalog_ginkgo_test.go @@ -102,7 +102,7 @@ var _ = Describe("Default runtime catalog", func() { Expect(sources[len(sources)-1]).To(Equal(NewBuiltinSource().Info())) listed, err := catalog.ListPresets(ctx) Expect(err).NotTo(HaveOccurred()) - Expect(presetSummaries(listed)).To(Equal([][2]string{{"file", "Plan"}, {"builtin", "Edit"}, {"builtin", "Read-only"}})) + Expect(presetSummaries(listed)).To(Equal([][2]string{{"file", "Plan"}, {"builtin", "Edit"}, {"builtin", "Lint"}, {"builtin", "Read-only"}})) resolution, err := catalog.ResolvePresets(ctx, []string{"plan"}) Expect(err).NotTo(HaveOccurred()) Expect(resolution.Resolved.Spec.Permissions.Mode).To(Equal(api.PermissionDefault)) diff --git a/pkg/runtimeprofiles/embedded_source_ginkgo_test.go b/pkg/runtimeprofiles/embedded_source_ginkgo_test.go index 60f22f53..94f5a054 100644 --- a/pkg/runtimeprofiles/embedded_source_ginkgo_test.go +++ b/pkg/runtimeprofiles/embedded_source_ginkgo_test.go @@ -97,7 +97,7 @@ var _ = Describe("Catalog host source precedence", func() { listed, err := catalog.ListPresets(ctx) Expect(err).NotTo(HaveOccurred()) Expect(presetSources(listed)).To(Equal([][2]string{ - {hostSourceID, "Acme debug"}, {hostSourceID, "Plan"}, {BuiltinSourceID, "Edit"}, {BuiltinSourceID, "Read-only"}, + {hostSourceID, "Acme debug"}, {hostSourceID, "Plan"}, {BuiltinSourceID, "Edit"}, {BuiltinSourceID, "Lint"}, {BuiltinSourceID, "Read-only"}, })) plan, err := catalog.GetPreset(ctx, "plan") Expect(err).NotTo(HaveOccurred()) @@ -124,7 +124,7 @@ var _ = Describe("Catalog host source precedence", func() { listed, err := catalog.ListPresets(ctx) Expect(err).NotTo(HaveOccurred()) Expect(presetSummaries(listed)).To(Equal([][2]string{ - {"file", "Acme debug"}, {"builtin", "Plan"}, {"builtin", "Edit"}, {"builtin", "Read-only"}, + {"file", "Acme debug"}, {"builtin", "Plan"}, {"builtin", "Edit"}, {"builtin", "Lint"}, {"builtin", "Read-only"}, })) debug, err := catalog.GetPreset(ctx, "ACME debug") Expect(err).NotTo(HaveOccurred()) From 53ae3d4a7a07e7d43d2c83f3c8cbf86e70f512ef Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Thu, 22 Oct 2026 22:55:39 +0300 Subject: [PATCH 11/77] security(codexhome): isolate read-only codex runs from execpolicy rules Codex execpolicy rules run matching commands outside the sandbox, even under a read-only sandbox with approval never. A user rule such as prefix_rule(["git","add"], decision="allow") could let a read-only run write the git index. `codex exec` can skip rules with --ignore-rules, but the app-server and TUI cannot. Read-only runs for those modes now start in a captain-managed CODEX_HOME under captain's config directory. It links only auth.json, config.toml and AGENTS.md from the user's home, so it carries no rules. Runs refuse a project .codex/rules layer that allows commands, because the isolated home cannot hide project rules. Session discovery now also scans the isolated home so its rollouts remain visible. BREAKING CHANGE: read-only runs fail when project execpolicy rules allow commands, and when the isolated home contains a rules directory. --- pkg/ai/history/codex_parser.go | 29 ++- .../codex_session_roots_ginkgo_test.go | 29 +++ pkg/codexhome/codexhome.go | 231 ++++++++++++++++++ pkg/codexhome/codexhome_ginkgo_test.go | 137 +++++++++++ 4 files changed, 415 insertions(+), 11 deletions(-) create mode 100644 pkg/ai/history/codex_session_roots_ginkgo_test.go create mode 100644 pkg/codexhome/codexhome.go create mode 100644 pkg/codexhome/codexhome_ginkgo_test.go diff --git a/pkg/ai/history/codex_parser.go b/pkg/ai/history/codex_parser.go index 680ae5ed..54d9993f 100644 --- a/pkg/ai/history/codex_parser.go +++ b/pkg/ai/history/codex_parser.go @@ -9,6 +9,7 @@ import ( "time" "github.com/flanksource/captain/pkg/api" + "github.com/flanksource/captain/pkg/codexhome" "github.com/flanksource/captain/pkg/jsonl" "github.com/segmentio/encoding/json" ) @@ -400,23 +401,29 @@ func sortedCodexPendingCalls(pending map[string]codexPendingCall) []codexPending return calls } +// FindCodexSessionFiles lists the rollouts under every home codex writes to: +// the user's, and the isolated one captain starts read-only runs in. func FindCodexSessionFiles() ([]string, error) { - home, err := os.UserHomeDir() + roots, err := codexhome.SessionRoots() if err != nil { return nil, err } - sessionsDir := filepath.Join(home, ".codex", "sessions") - if _, err := os.Stat(sessionsDir); os.IsNotExist(err) { - return nil, nil - } var files []string - err = filepath.Walk(sessionsDir, func(path string, info os.FileInfo, err error) error { - if err == nil && !info.IsDir() && strings.HasSuffix(path, ".jsonl") { - files = append(files, path) + for _, sessionsDir := range roots { + if _, err := os.Stat(sessionsDir); os.IsNotExist(err) { + continue } - return nil - }) - return files, err + err = filepath.Walk(sessionsDir, func(path string, info os.FileInfo, err error) error { + if err == nil && !info.IsDir() && strings.HasSuffix(path, ".jsonl") { + files = append(files, path) + } + return nil + }) + if err != nil { + return nil, err + } + } + return files, nil } func IsCodexSession(path string) bool { diff --git a/pkg/ai/history/codex_session_roots_ginkgo_test.go b/pkg/ai/history/codex_session_roots_ginkgo_test.go new file mode 100644 index 00000000..e9193ffe --- /dev/null +++ b/pkg/ai/history/codex_session_roots_ginkgo_test.go @@ -0,0 +1,29 @@ +package history + +import ( + "os" + "path/filepath" + + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("Codex session discovery", func() { + It("finds rollouts written by a read-only run in captain's isolated CODEX_HOME", func() { + root := GinkgoT().TempDir() + GinkgoT().Setenv("CODEX_HOME", filepath.Join(root, "user-codex")) + GinkgoT().Setenv("XDG_CONFIG_HOME", filepath.Join(root, "config")) + user := filepath.Join(root, "user-codex", "sessions", "2026", "10", "22", "rollout-a.jsonl") + readOnly := filepath.Join(root, "config", "captain", "codex-read-only", "sessions", "2026", "10", "22", "rollout-b.jsonl") + for _, path := range []string{user, readOnly} { + Expect(os.MkdirAll(filepath.Dir(path), 0o755)).To(Succeed()) + Expect(os.WriteFile(path, []byte("{}\n"), 0o600)).To(Succeed()) + } + + files, err := FindCodexSessionFiles() + + Expect(err).NotTo(HaveOccurred()) + Expect(files).To(ConsistOf(user, readOnly)) + Expect(IsCodexSession(readOnly)).To(BeTrue()) + }) +}) diff --git a/pkg/codexhome/codexhome.go b/pkg/codexhome/codexhome.go new file mode 100644 index 00000000..0d6b3732 --- /dev/null +++ b/pkg/codexhome/codexhome.go @@ -0,0 +1,231 @@ +// Package codexhome owns the CODEX_HOME a read-only codex run starts in. +// +// Codex execpolicy `.rules` files run a matching command outside the sandbox, +// even under a read-only sandbox with approval never, so a user's +// `prefix_rule(["git","add"], decision="allow")` would let a read-only run +// write the git index. `codex exec` can skip them with --ignore-rules; the +// app-server and the interactive TUI cannot, so captain starts those in a +// captain-managed home that links only what codex needs and has no rules. +package codexhome + +import ( + "errors" + "fmt" + "io/fs" + "os" + "path/filepath" + "regexp" + "strings" + + "github.com/flanksource/captain/pkg/captainconfig" +) + +// linked are the user-home entries a read-only run needs: the login, the +// configuration (which has no field that declares rules), and the user's +// instructions. Everything else codex writes there itself. +var linked = []string{"auth.json", "config.toml", "AGENTS.md"} + +// UserHome is the home codex uses by default: $CODEX_HOME, else ~/.codex. +func UserHome() (string, error) { + if home := os.Getenv("CODEX_HOME"); home != "" { + return home, nil + } + home, err := os.UserHomeDir() + if err != nil { + return "", fmt.Errorf("resolve home directory: %w", err) + } + return filepath.Join(home, ".codex"), nil +} + +// ReadOnlyHome is the stable captain-managed CODEX_HOME for read-only runs. It +// lives under captain's config home rather than a cache, because codex writes +// the run's session rollouts into it and they are the run's history. +func ReadOnlyHome() (string, error) { + home, err := captainconfig.Home() + if err != nil { + return "", err + } + return filepath.Join(home, "codex-read-only"), nil +} + +// SessionRoots are the directories codex writes rollouts to: the user's home +// and the read-only home. +func SessionRoots() ([]string, error) { + user, err := UserHome() + if err != nil { + return nil, err + } + readOnly, err := ReadOnlyHome() + if err != nil { + return nil, err + } + return []string{filepath.Join(user, "sessions"), filepath.Join(readOnly, "sessions")}, nil +} + +// PrepareReadOnly creates the read-only home and links the user's login, +// configuration and instructions into it. A rules directory in it is refused +// rather than removed: with approval never nothing should have written one. +func PrepareReadOnly() (string, error) { + user, err := UserHome() + if err != nil { + return "", err + } + home, err := ReadOnlyHome() + if err != nil { + return "", err + } + if err := os.MkdirAll(home, 0o700); err != nil { + return "", fmt.Errorf("create read-only CODEX_HOME: %w", err) + } + if rules := filepath.Join(home, "rules"); exists(rules) { + return "", fmt.Errorf("read-only CODEX_HOME has an execpolicy rules directory %s; remove it, a read-only run must not load rules", rules) + } + if err := reconcileLogin(filepath.Join(user, "auth.json"), filepath.Join(home, "auth.json")); err != nil { + return "", err + } + for _, name := range linked { + if err := linkInto(filepath.Join(user, name), filepath.Join(home, name)); err != nil { + return "", err + } + } + return home, nil +} + +// reconcileLogin keeps one login across the two homes. Codex 0.163.0 writes +// auth.json in place (FileAuthStorage::save opens it with truncate), so a +// token refresh goes through the link to the user's file. Should a codex ever +// write it by rename instead, the link becomes a regular file: a newer one is +// a refreshed login and is moved back over the user's (an atomic rename) before +// re-linking; an older one is superseded by the user's newer login. Anything +// else — no user login to compare with, or a same-age file with different +// content — is refused, so a refreshed token is never dropped. +func reconcileLogin(user, isolated string) error { + info, err := os.Lstat(isolated) + if errors.Is(err, fs.ErrNotExist) || err == nil && info.Mode()&fs.ModeSymlink != 0 { + return nil + } + if err != nil { + return err + } + if !info.Mode().IsRegular() { + return fmt.Errorf("read-only CODEX_HOME login %s is a %s, not a link or a file", isolated, info.Mode().Type()) + } + current, err := os.Stat(user) + if err != nil { + return fmt.Errorf("read-only CODEX_HOME holds its own login %s and the user login cannot be compared: %w", isolated, err) + } + switch { + case info.ModTime().After(current.ModTime()): + if err := os.Rename(isolated, user); err != nil { + return fmt.Errorf("move the refreshed codex login %s back to %s: %w", isolated, user, err) + } + return nil + case info.ModTime().Before(current.ModTime()) || sameContent(user, isolated): + return os.Remove(isolated) + default: + return fmt.Errorf("read-only CODEX_HOME login %s differs from %s but is not newer; resolve it by hand", isolated, user) + } +} + +func sameContent(left, right string) bool { + a, errA := os.ReadFile(left) + b, errB := os.ReadFile(right) + return errA == nil && errB == nil && string(a) == string(b) +} + +// ForRun is the CODEX_HOME a codex process without --ignore-rules (the +// app-server, the interactive TUI) starts in: "" (inherit) unless the run is +// read-only, then the prepared isolated home, after refusing project rules the +// isolated home cannot hide. +func ForRun(readOnly bool, cwd string) (string, error) { + if !readOnly { + return "", nil + } + if err := RequireNoProjectAllowRules(cwd); err != nil { + return "", err + } + return PrepareReadOnly() +} + +// linkInto points target at source, replacing a link captain left there +// before, and removes the link when the user has no such file. A target that +// is not a link was written by something else, and is refused rather than +// deleted: codex writes config.toml and auth.json through the link. +func linkInto(source, target string) error { + if info, err := os.Lstat(target); err == nil && info.Mode()&fs.ModeSymlink == 0 { + return fmt.Errorf("read-only CODEX_HOME entry %s is no longer a link to %s; move its changes into %s and remove it", target, source, source) + } + if !exists(source) { + if err := os.Remove(target); err != nil && !errors.Is(err, fs.ErrNotExist) { + return fmt.Errorf("remove stale %s: %w", target, err) + } + return nil + } + if current, err := os.Readlink(target); err == nil && current == source { + return nil + } + if err := os.Remove(target); err != nil && !errors.Is(err, fs.ErrNotExist) { + return fmt.Errorf("replace %s: %w", target, err) + } + if err := os.Symlink(source, target); err != nil { + // A concurrent run may have linked it first. + if current, readErr := os.Readlink(target); readErr == nil && current == source { + return nil + } + return fmt.Errorf("link %s into the read-only CODEX_HOME: %w", source, err) + } + return nil +} + +var ( + prefixRule = regexp.MustCompile(`prefix_rule\s*\(`) + nonAllowDecided = regexp.MustCompile(`decision\s*=\s*"(forbidden|prompt)"`) +) + +// RequireNoProjectAllowRules refuses a working tree whose codex project layers +// carry a rule that allows a command. Codex reads `.codex/rules/*.rules` from +// every directory between the working directory and the project root (the +// nearest ancestor with .git, or the working directory alone), and the +// isolated home cannot hide them. A rule with no decision defaults to allow. +func RequireNoProjectAllowRules(cwd string) error { + if cwd == "" { + return nil + } + for _, dir := range projectLayers(cwd) { + files, err := filepath.Glob(filepath.Join(dir, ".codex", "rules", "*.rules")) + if err != nil { + return err + } + for _, file := range files { + data, err := os.ReadFile(file) + if err != nil { + return fmt.Errorf("read project execpolicy rules: %w", err) + } + text := string(data) + if len(prefixRule.FindAllString(text, -1)) > len(nonAllowDecided.FindAllString(text, -1)) { + return fmt.Errorf("project execpolicy rules %s allow commands to run outside the read-only sandbox; remove the allow rules or run without permissions.access read-only", file) + } + } + } + return nil +} + +// projectLayers lists cwd and its ancestors up to the nearest one holding .git; +// with no .git anywhere, cwd alone. +func projectLayers(cwd string) []string { + var dirs []string + for dir := filepath.Clean(cwd); ; dir = filepath.Dir(dir) { + dirs = append(dirs, dir) + if exists(filepath.Join(dir, ".git")) { + return dirs + } + if parent := filepath.Dir(dir); parent == dir || strings.TrimSpace(parent) == "" { + return dirs[:1] + } + } +} + +func exists(path string) bool { + _, err := os.Lstat(path) + return err == nil +} diff --git a/pkg/codexhome/codexhome_ginkgo_test.go b/pkg/codexhome/codexhome_ginkgo_test.go new file mode 100644 index 00000000..ff7911e8 --- /dev/null +++ b/pkg/codexhome/codexhome_ginkgo_test.go @@ -0,0 +1,137 @@ +package codexhome + +import ( + "os" + "path/filepath" + "testing" + "time" + + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +func TestCodexHome(t *testing.T) { + RegisterFailHandler(Fail) + RunSpecs(t, "Codex Home Suite") +} + +func writeFile(path, body string) { + Expect(os.MkdirAll(filepath.Dir(path), 0o755)).To(Succeed()) + Expect(os.WriteFile(path, []byte(body), 0o600)).To(Succeed()) +} + +var _ = Describe("read-only CODEX_HOME", func() { + var user, config string + + BeforeEach(func() { + root := GinkgoT().TempDir() + user, config = filepath.Join(root, "user-codex"), filepath.Join(root, "config") + GinkgoT().Setenv("CODEX_HOME", user) + GinkgoT().Setenv("XDG_CONFIG_HOME", config) + writeFile(filepath.Join(user, "auth.json"), `{"tokens":{}}`) + writeFile(filepath.Join(user, "config.toml"), "model = \"gpt-6.1-sol\"\n") + writeFile(filepath.Join(user, "rules", "default.rules"), `prefix_rule(pattern=["git","add"], decision="allow")`) + }) + + It("links what codex needs from the user's home and carries over no rules", func() { + home, err := PrepareReadOnly() + Expect(err).NotTo(HaveOccurred()) + + Expect(home).To(Equal(filepath.Join(config, "captain", "codex-read-only"))) + for _, name := range []string{"auth.json", "config.toml"} { + target, err := os.Readlink(filepath.Join(home, name)) + Expect(err).NotTo(HaveOccurred()) + Expect(target).To(Equal(filepath.Join(user, name))) + } + Expect(filepath.Join(home, "rules")).NotTo(BeAnExistingFile()) + Expect(filepath.Join(home, "AGENTS.md")).NotTo(BeAnExistingFile(), "a missing source is not linked") + }) + + It("refuses a home where something has written rules", func() { + home, err := PrepareReadOnly() + Expect(err).NotTo(HaveOccurred()) + writeFile(filepath.Join(home, "rules", "default.rules"), `prefix_rule(pattern=["git"], decision="allow")`) + + _, err = PrepareReadOnly() + Expect(err).To(MatchError(ContainSubstring(filepath.Join(home, "rules")))) + }) + + Describe("a login codex replaced the link with", func() { + var home, isolated string + BeforeEach(func() { + var err error + home, err = PrepareReadOnly() + Expect(err).NotTo(HaveOccurred()) + isolated = filepath.Join(home, "auth.json") + Expect(os.Remove(isolated)).To(Succeed()) + writeFile(isolated, `{"tokens":{"refresh_token":"isolated"}}`) + }) + + It("moves a newer login back over the user's and re-links it", func() { + past := time.Now().Add(-time.Hour) + Expect(os.Chtimes(filepath.Join(user, "auth.json"), past, past)).To(Succeed()) + + _, err := PrepareReadOnly() + Expect(err).NotTo(HaveOccurred()) + + Expect(os.ReadFile(filepath.Join(user, "auth.json"))).To(Equal([]byte(`{"tokens":{"refresh_token":"isolated"}}`))) + Expect(os.Readlink(isolated)).To(Equal(filepath.Join(user, "auth.json"))) + }) + + It("re-links over an older copy and keeps the user's newer login", func() { + past := time.Now().Add(-time.Hour) + Expect(os.Chtimes(isolated, past, past)).To(Succeed()) + + _, err := PrepareReadOnly() + Expect(err).NotTo(HaveOccurred()) + + Expect(os.ReadFile(filepath.Join(user, "auth.json"))).To(Equal([]byte(`{"tokens":{}}`))) + Expect(os.Readlink(isolated)).To(Equal(filepath.Join(user, "auth.json"))) + }) + }) + + It("refuses a linked entry that became a regular file rather than deleting it", func() { + home, err := PrepareReadOnly() + Expect(err).NotTo(HaveOccurred()) + Expect(os.Remove(filepath.Join(home, "config.toml"))).To(Succeed()) + writeFile(filepath.Join(home, "config.toml"), "model = \"edited\"\n") + + _, err = PrepareReadOnly() + Expect(err).To(MatchError(ContainSubstring(filepath.Join(home, "config.toml")))) + }) + + It("lists the read-only home's sessions beside the user's", func() { + roots, err := SessionRoots() + Expect(err).NotTo(HaveOccurred()) + Expect(roots).To(ContainElement(filepath.Join(config, "captain", "codex-read-only", "sessions"))) + }) +}) + +var _ = Describe("project execpolicy rules", func() { + DescribeTable("refuses a project rules file that allows a command", + func(files map[string]string, cwd string, want string) { + root := GinkgoT().TempDir() + for path, body := range files { + writeFile(filepath.Join(root, path), body) + } + err := RequireNoProjectAllowRules(filepath.Join(root, cwd)) + if want == "" { + Expect(err).NotTo(HaveOccurred()) + return + } + Expect(err).To(MatchError(ContainSubstring(filepath.Join(root, want)))) + }, + Entry("an allow rule at the repository root, run from a subdirectory", + map[string]string{"repo/.git/HEAD": "", "repo/.codex/rules/team.rules": `prefix_rule(pattern=["git","add"], decision="allow")`, "repo/sub/x": ""}, + "repo/sub", "repo/.codex/rules/team.rules"), + Entry("a rule with no decision, which codex treats as allow", + map[string]string{"repo/.git/HEAD": "", "repo/.codex/rules/team.rules": `prefix_rule(pattern=["npx"])`}, + "repo", "repo/.codex/rules/team.rules"), + Entry("forbidden and prompt rules only", + map[string]string{"repo/.git/HEAD": "", "repo/.codex/rules/team.rules": "prefix_rule(pattern=[\"rm\"], decision=\"forbidden\")\nprefix_rule(pattern=[\"git\"], decision=\"prompt\")"}, + "repo", ""), + Entry("rules above the repository root are not codex's project layers", + map[string]string{".codex/rules/outer.rules": `prefix_rule(pattern=["git"], decision="allow")`, "repo/.git/HEAD": ""}, + "repo", ""), + ) +}) From f490e9e8385eab516bbbf0c57e387560904afef3 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Thu, 22 Oct 2026 22:55:43 +0300 Subject: [PATCH 12/77] fix(codex): isolate read-only codex runs and scope app-server events to the run's thread Execpolicy allow rules could run commands outside the sandbox even under read-only, so read-only runs now start in an isolated CODEX_HOME and pass --ignore-rules. A codex process cannot change CODEX_HOME, so a session refuses a turn that needs a different home. Notifications from sub-agent threads are dropped so they no longer replace the run's session id or end its turn. --- pkg/ai/provider/codex_appserver.go | 21 +++++++++-- pkg/ai/provider/codex_appserver_process.go | 16 ++++++++- .../codex_appserver_subagent_ginkgo_test.go | 36 +++++++++++++++++++ pkg/ai/provider/codex_appserver_test.go | 2 +- pkg/ai/provider/codex_appserver_turn.go | 11 ++++++ pkg/ai/provider/codex_cli.go | 4 ++- 6 files changed, 84 insertions(+), 6 deletions(-) create mode 100644 pkg/ai/provider/codex_appserver_subagent_ginkgo_test.go diff --git a/pkg/ai/provider/codex_appserver.go b/pkg/ai/provider/codex_appserver.go index 7f2ea841..3b38c7eb 100644 --- a/pkg/ai/provider/codex_appserver.go +++ b/pkg/ai/provider/codex_appserver.go @@ -55,6 +55,10 @@ type CodexAppServer struct { // runLabels is the host's identification of the current run, recorded here // for the same reason posture is: the spawn path cannot reach the request. runLabels map[string]string + // codexHome is the CODEX_HOME the running server was started with: empty + // for the user's, the isolated home for a read-only run. A process cannot + // change it, so a later turn that needs the other is refused. + codexHome string callerToolsMu sync.Mutex callerToolsRuntime *callertools.Runtime @@ -148,9 +152,13 @@ func (c *CodexAppServer) ExecuteStream(ctx context.Context, req ai.Request) (<-c if _, err := translateCodexSandbox(api.RuntimeOf(api.OpenAI, api.ModeAgent), req); err != nil { return nil, err } + codexHome, err := codexRunHome(req) + if err != nil { + return nil, fmt.Errorf("codex app-server: %w", err) + } req = c.beginTurn(req) req.Prompt.AppendSystem = strings.Join([]string{req.Prompt.AppendSystem, ai.QuestionInstructions("request_user_input", c.cfg.OnApproval != nil && req.Permissions.Mode == api.PermissionPlan)}, "\n\n") - if err := c.ensureStarted(ctx); err != nil { + if err := c.ensureStarted(ctx, codexHome); err != nil { c.turnMu.Unlock() return nil, err } @@ -280,17 +288,21 @@ func (c *CodexAppServer) clearActive(ts *turnState) { // ensureStarted lazily spawns the supervised server, binds the JSON-RPC client // to its stdio, and performs the initialize handshake (serialized by turnMu). -func (c *CodexAppServer) ensureStarted(ctx context.Context) error { +func (c *CodexAppServer) ensureStarted(ctx context.Context, codexHome string) error { if c.client() != nil { + if c.codexHome != codexHome { + return fmt.Errorf("codex app-server: this session's server runs with CODEX_HOME %q but the turn needs %q; permissions.access cannot change within a session", c.codexHome, codexHome) + } return nil } + c.codexHome = codexHome if _, err := osexec.LookPath("codex"); err != nil { return fmt.Errorf("%w: %v", ai.ErrCLINotFound, err) } ready := make(chan error, 1) var process *exec.Process - sup := newCodexAppServerProcess(c.cfg).WithStdioPipe().Supervise(exec.SuperviseOptions{ + sup := newCodexAppServerProcess(c.cfg, codexHome).WithStdioPipe().Supervise(exec.SuperviseOptions{ // No restart: a crash surfaces as EventError, never a silent retry. RestartPolicy: exec.RestartNo, Task: c.taskIdentity(), @@ -541,6 +553,9 @@ func (c *CodexAppServer) handleNotification(method string, params json.RawMessag if ts == nil { return } + if !ts.ownsThread(parseAppServerNotif(params).threadID()) { + return + } ctx := appServerEventContext{Model: ts.model, Usage: ts.usage, UsagePresent: &ts.usagePresent, Context: &ts.context} if ts.recordFileChange(method, params) { return diff --git a/pkg/ai/provider/codex_appserver_process.go b/pkg/ai/provider/codex_appserver_process.go index 33495915..90dd3d86 100644 --- a/pkg/ai/provider/codex_appserver_process.go +++ b/pkg/ai/provider/codex_appserver_process.go @@ -5,10 +5,13 @@ import ( "strings" "github.com/flanksource/captain/pkg/ai" + "github.com/flanksource/captain/pkg/codexhome" "github.com/flanksource/clicky/exec" ) -func newCodexAppServerProcess(cfg ai.Config) *exec.Process { +// newCodexAppServerProcess builds the app-server command. codexHome, when set, +// is the isolated home a read-only run starts in (see codexRunHome). +func newCodexAppServerProcess(cfg ai.Config, codexHome string) *exec.Process { args := []string{"app-server", "-c", fmt.Sprintf("tools.experimental_request_user_input.enabled=%t", cfg.OnApproval != nil)} args = append(args, "-c", "features.default_mode_request_user_input=false") if cfg.APIURL != "" { @@ -18,9 +21,20 @@ func newCodexAppServerProcess(cfg ai.Config) *exec.Process { if cfg.APIKey != "" { process.WithEnv(map[string]string{"OPENAI_API_KEY": cfg.APIKey}) } + if codexHome != "" { + process.WithEnv(map[string]string{"CODEX_HOME": codexHome}) + } return process } +// codexRunHome is the CODEX_HOME a codex process that cannot pass +// --ignore-rules runs in. Execpolicy allow rules run a matching command +// outside the sandbox even under read-only with approval never, so a +// read-only run starts in captain's isolated home, which has none. +func codexRunHome(req ai.Request) (string, error) { + return codexhome.ForRun(req.Permissions.EffectiveAccess().ReadOnly(), req.Cwd()) +} + func appServerProcessError(err error, stderr string) error { if detail := strings.TrimSpace(stderr); detail != "" { return fmt.Errorf("%w: %s", err, detail) diff --git a/pkg/ai/provider/codex_appserver_subagent_ginkgo_test.go b/pkg/ai/provider/codex_appserver_subagent_ginkgo_test.go new file mode 100644 index 00000000..207d0845 --- /dev/null +++ b/pkg/ai/provider/codex_appserver_subagent_ginkgo_test.go @@ -0,0 +1,36 @@ +package provider + +import ( + "encoding/json" + + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" + + "github.com/flanksource/captain/pkg/ai" +) + +var _ = Describe("Codex app-server sub-agent threads", func() { + It("keeps a spawned sub-agent's notifications out of the run's own turn", func() { + client, turn := activeGinkgoTurn() + turn.setIDs("main-thread", "turn-1") + + client.handleNotification("thread/started", json.RawMessage(`{"thread":{"id":"sub-thread"}}`)) + client.handleNotification("item/agentMessage/delta", json.RawMessage(`{"threadId":"sub-thread","itemId":"m1","delta":"sub-agent text"}`)) + client.handleNotification("turn/completed", json.RawMessage(`{"threadId":"sub-thread","turn":{"id":"sub-turn","status":"completed"}}`)) + + Expect(drainEvents(turn)).To(BeEmpty(), "a sub-agent's session start, text and completion are not the run's") + Expect(turn.terminal).NotTo(BeClosed(), "a sub-agent finishing must not end the parent turn") + + client.handleNotification("item/agentMessage/delta", json.RawMessage(`{"threadId":"main-thread","itemId":"m2","delta":"parent text"}`)) + Expect(drainEvents(turn)).To(ConsistOf(HaveField("Text", "parent text"))) + }) + + It("still reports the run's own thread start before its id is known", func() { + client, turn := activeGinkgoTurn() + + client.handleNotification("thread/started", json.RawMessage(`{"thread":{"id":"main-thread"}}`)) + + Expect(drainEvents(turn)).To(ConsistOf(SatisfyAll( + HaveField("Kind", ai.EventSystem), HaveField("SessionID", "main-thread")))) + }) +}) diff --git a/pkg/ai/provider/codex_appserver_test.go b/pkg/ai/provider/codex_appserver_test.go index 619a16bb..cb22120c 100644 --- a/pkg/ai/provider/codex_appserver_test.go +++ b/pkg/ai/provider/codex_appserver_test.go @@ -26,7 +26,7 @@ func TestNewCodexAppServer_Defaults(t *testing.T) { func TestCodexAppServerProcessHonoursAPIURL(t *testing.T) { process := newCodexAppServerProcess(ai.Config{ APIURL: "http://127.0.0.1:4020/v1", APIKey: "captain-mock", - }) + }, "") assert.Equal(t, "codex", process.Cmd) assert.Equal(t, []string{ "app-server", diff --git a/pkg/ai/provider/codex_appserver_turn.go b/pkg/ai/provider/codex_appserver_turn.go index df3c5a05..8923fd4c 100644 --- a/pkg/ai/provider/codex_appserver_turn.go +++ b/pkg/ai/provider/codex_appserver_turn.go @@ -108,6 +108,17 @@ func lastNonBlankLine(text string) string { return "" } +// ownsThread reports whether a notification naming threadID belongs to this +// turn. A sub-agent the model spawns runs in a thread of its own on the same +// app-server; its thread/started would otherwise replace the run's session id +// and its turn/completed would end the parent's turn. Its rollout is still +// written, and filed under its own thread, by the monitor. A notification +// naming no thread, or arriving before the run's thread is known, is the run's. +func (ts *turnState) ownsThread(threadID string) bool { + own, _ := ts.ids() + return threadID == "" || own == "" || threadID == own +} + func (ts *turnState) setIDs(threadID, turnID string) { ts.idMu.Lock() ts.threadID = threadID diff --git a/pkg/ai/provider/codex_cli.go b/pkg/ai/provider/codex_cli.go index c6376254..216786be 100644 --- a/pkg/ai/provider/codex_cli.go +++ b/pkg/ai/provider/codex_cli.go @@ -242,7 +242,9 @@ func buildCodexCLIArgs(cfg codexCLIConfig, req ai.Request) ([]string, func(), er if req.Memory.SkipUser { args = append(args, "--ignore-user-config") } - if req.Memory.SkipProject || req.Memory.SkipHooks { + // Execpolicy allow rules run a matching command outside the sandbox even + // under read-only with approval never, so a read-only run skips them. + if req.Memory.SkipProject || req.Memory.SkipHooks || req.Permissions.EffectiveAccess().ReadOnly() { args = append(args, "--ignore-rules") } if binary, ok := captainBinary(); ok && api.MonitorHooksEnabled(req) { From 3b2eda5a2b62f60e1750264799436ccad2f82f26 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Thu, 22 Oct 2026 22:55:48 +0300 Subject: [PATCH 13/77] security(access): deny out-of-process tools and execpolicy rules in read-only runs Claude's tool denies do not follow sub-agents, teams, peer messages, crons or worktrees the agent creates, so read-only runs could still write through them. Those tools are now denied, while read-only listing tools stay allowed. Codex execpolicy allow rules run commands outside the read-only sandbox. `codex exec` now passes --ignore-rules, and the app-server and cmux TUI start in an isolated CODEX_HOME without user rules. BREAKING CHANGE: read-only codex runs are refused when project rules in the tree allow a command, and read-only Claude runs lose the newly listed tools. --- pkg/ai/provider/access_argv_ginkgo_test.go | 61 +++++++++++++++++++ .../provider/cmux/access_env_ginkgo_test.go | 34 +++++++++++ pkg/ai/provider/cmux/provider.go | 27 +++++++- pkg/api/access.go | 12 +++- pkg/api/access_compile.go | 26 +++++++- pkg/api/access_ginkgo_test.go | 28 ++++++++- pkg/api/agent_resources.go | 10 +++ pkg/api/permission_capabilities.go | 6 +- pkg/cli/permissions_access.go | 1 + pkg/cli/permissions_access_ginkgo_test.go | 1 + 10 files changed, 199 insertions(+), 7 deletions(-) create mode 100644 pkg/ai/provider/cmux/access_env_ginkgo_test.go diff --git a/pkg/ai/provider/access_argv_ginkgo_test.go b/pkg/ai/provider/access_argv_ginkgo_test.go index 8b231510..1d4b7237 100644 --- a/pkg/ai/provider/access_argv_ginkgo_test.go +++ b/pkg/ai/provider/access_argv_ginkgo_test.go @@ -1,9 +1,14 @@ package provider import ( + "context" + "os" + "path/filepath" + "slices" "strings" "github.com/flanksource/captain/pkg/ai" + "github.com/flanksource/captain/pkg/ai/provider/jsonrpc" "github.com/flanksource/captain/pkg/api" . "github.com/onsi/ginkgo/v2" . "github.com/onsi/gomega" @@ -42,6 +47,62 @@ var _ = Describe("permissions.access read-only on the wire", func() { Expect(turn["sandboxPolicy"]).To(HaveKeyWithValue("type", "readOnly")) }) + DescribeTable("skips execpolicy rules on codex exec only under read-only", + func(req ai.Request, want bool) { + args, cleanup, err := buildCodexCLIArgs(codexCLIConfig{Model: "gpt-5.5"}, req) + Expect(err).NotTo(HaveOccurred()) + DeferCleanup(cleanup) + Expect(slices.Contains(args, "--ignore-rules")).To(Equal(want)) + }, + Entry("read-only", compiledReadOnly(api.RuntimeOf(api.OpenAI, api.ModeCLI)), true), + Entry("no access", ai.Request{Prompt: api.Prompt{User: "review"}}, false), + Entry("full", ai.Request{Prompt: api.Prompt{User: "review"}, Permissions: api.Permissions{Access: api.AccessFull}}, false), + ) + + Describe("codex app-server CODEX_HOME", func() { + var user, config string + BeforeEach(func() { + root := GinkgoT().TempDir() + user, config = filepath.Join(root, "user-codex"), filepath.Join(root, "config") + GinkgoT().Setenv("CODEX_HOME", user) + GinkgoT().Setenv("XDG_CONFIG_HOME", config) + Expect(os.MkdirAll(filepath.Join(user, "rules"), 0o755)).To(Succeed()) + Expect(os.WriteFile(filepath.Join(user, "auth.json"), []byte("{}"), 0o600)).To(Succeed()) + }) + + It("starts a read-only run in the isolated home and any other run in the user's", func() { + readOnly := compiledReadOnly(api.RuntimeOf(api.OpenAI, api.ModeAgent)) + home, err := codexRunHome(readOnly) + Expect(err).NotTo(HaveOccurred()) + Expect(home).To(Equal(filepath.Join(config, "captain", "codex-read-only"))) + Expect(newCodexAppServerProcess(ai.Config{}, home).Env).To(HaveKeyWithValue("CODEX_HOME", home)) + Expect(filepath.Join(home, "rules")).NotTo(BeAnExistingFile()) + + home, err = codexRunHome(ai.Request{Prompt: api.Prompt{User: "review"}}) + Expect(err).NotTo(HaveOccurred()) + Expect(home).To(BeEmpty()) + Expect(newCodexAppServerProcess(ai.Config{}, home).Env).NotTo(HaveKey("CODEX_HOME")) + }) + + It("refuses a read-only run in a tree whose project rules allow a command", func() { + repo := GinkgoT().TempDir() + rules := filepath.Join(repo, ".codex", "rules", "team.rules") + Expect(os.MkdirAll(filepath.Join(repo, ".git"), 0o755)).To(Succeed()) + Expect(os.MkdirAll(filepath.Dir(rules), 0o755)).To(Succeed()) + Expect(os.WriteFile(rules, []byte(`prefix_rule(pattern=["git","add"], decision="allow")`), 0o600)).To(Succeed()) + req := compiledReadOnly(api.RuntimeOf(api.OpenAI, api.ModeAgent)) + req.SetCwd(repo) + + _, err := codexRunHome(req) + Expect(err).To(MatchError(ContainSubstring(rules))) + }) + + It("refuses a turn whose access differs from the running app-server's home", func() { + server := &CodexAppServer{codexHome: "/isolated", rpc: &jsonrpc.Client{}} + Expect(server.ensureStarted(context.Background(), "")).To(MatchError(ContainSubstring("CODEX_HOME"))) + }) + }) + It("denies claude's write, shell and sub-agent tools with strict MCP", func() { args, cleanup, err := buildClaudeCLIArgs("claude-sonnet-5", compiledReadOnly(api.RuntimeOf(api.Anthropic, api.ModeCLI))) Expect(err).NotTo(HaveOccurred()) diff --git a/pkg/ai/provider/cmux/access_env_ginkgo_test.go b/pkg/ai/provider/cmux/access_env_ginkgo_test.go new file mode 100644 index 00000000..289b0a72 --- /dev/null +++ b/pkg/ai/provider/cmux/access_env_ginkgo_test.go @@ -0,0 +1,34 @@ +package cmux + +import ( + "path/filepath" + + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" + + "github.com/flanksource/captain/pkg/ai" + "github.com/flanksource/captain/pkg/api" +) + +var _ = Describe("cmux agent environment under permissions.access", func() { + BeforeEach(func() { + root := GinkgoT().TempDir() + GinkgoT().Setenv("CODEX_HOME", filepath.Join(root, "user-codex")) + GinkgoT().Setenv("XDG_CONFIG_HOME", filepath.Join(root, "config")) + }) + + DescribeTable("starts read-only codex in the isolated CODEX_HOME, since the TUI has no --ignore-rules", + func(agent string, access api.AccessLevel, wantHome bool) { + env, err := agentEnv(agent, ai.Request{Permissions: api.Permissions{Access: access}}) + Expect(err).NotTo(HaveOccurred()) + if wantHome { + Expect(env).To(HaveKeyWithValue("CODEX_HOME", HaveSuffix(filepath.Join("captain", "codex-read-only")))) + } else { + Expect(env).NotTo(HaveKey("CODEX_HOME")) + } + }, + Entry("read-only codex", "codex", api.AccessReadOnly, true), + Entry("codex without access", "codex", api.AccessLevel(""), false), + Entry("read-only claude", "claude", api.AccessReadOnly, false), + ) +}) diff --git a/pkg/ai/provider/cmux/provider.go b/pkg/ai/provider/cmux/provider.go index 67f9a314..f1d8a2e6 100644 --- a/pkg/ai/provider/cmux/provider.go +++ b/pkg/ai/provider/cmux/provider.go @@ -27,6 +27,7 @@ import ( "github.com/flanksource/captain/pkg/ai/callertools" aitools "github.com/flanksource/captain/pkg/ai/tools" "github.com/flanksource/captain/pkg/api" + "github.com/flanksource/captain/pkg/codexhome" "github.com/flanksource/commons/logger" ) @@ -300,6 +301,26 @@ func cmuxExtraArgs(agent string, req ai.Request) (any, error) { } } +// agentEnv is the environment the agent command runs with: the run's own, plus +// for read-only codex the isolated CODEX_HOME. The interactive codex TUI has +// no --ignore-rules, and an execpolicy allow rule runs its command outside the +// read-only sandbox. +func agentEnv(agent string, req ai.Request) (map[string]string, error) { + env := req.EnvMap() + if agent != "codex" { + return env, nil + } + home, err := codexhome.ForRun(req.Permissions.EffectiveAccess().ReadOnly(), req.Cwd()) + if err != nil || home == "" { + return env, err + } + if env == nil { + env = map[string]string{} + } + env["CODEX_HOME"] = home + return env, nil +} + // decodeCLIArgs round-trips the free-form CLIArgs map through JSON into the typed // option struct, failing loud on a type mismatch rather than silently dropping it. func decodeCLIArgs(args map[string]any, out any) error { @@ -368,6 +389,10 @@ func (p *Provider) execute(ctx context.Context, req ai.Request, r *run) (*ai.Usa log.Warnf("cmux: %s", warning) } tools := permissions.Tools + env, err := agentEnv(agent, req) + if err != nil { + return nil, 0, fmt.Errorf("cmux: %w", err) + } agentCommand := launch.launchCommand(withEnv(AgentCommand(AgentCommandOpts{ Agent: agent, Model: model, @@ -382,7 +407,7 @@ func (p *Provider) execute(ctx context.Context, req ai.Request, r *run) (*ai.Usa ConfigOverrides: launch.configOverrides, Memory: req.Memory, Extra: extra, - }), req.EnvMap())) + }), env)) timeout := r.timeout() // ctxLog routes internal step-by-step narration to the run's clicky task diff --git a/pkg/api/access.go b/pkg/api/access.go index 1f86d89b..17551f98 100644 --- a/pkg/api/access.go +++ b/pkg/api/access.go @@ -43,8 +43,16 @@ var readOnlyDeniedAliases = []string{"edit", "write", "shell"} // but claude's sandbox does not, because it only wraps Bash. var writeAliases = []string{"edit", "write"} -// claudeSubAgentTools spawn agents that would not inherit a per-tool deny list. -var claudeSubAgentTools = []string{"Agent", "Task", "Workflow"} +// claudeOutOfProcessTools act outside the agent's own process, where its tool +// denies do not follow: they spawn agents or teams that would not inherit the +// deny list, message a peer or remote Claude session that could write for it +// (SendMessage, RemoteTrigger), schedule prompts that run later, possibly in a +// durable task file (CronCreate, CronDelete), or create and remove git +// worktrees (EnterWorktree, ExitWorktree). Listing peers and crons only reads. +var claudeOutOfProcessTools = []string{ + "Agent", "Task", "Workflow", "TeamCreate", "TeamDelete", + "SendMessage", "RemoteTrigger", "CronCreate", "CronDelete", "EnterWorktree", "ExitWorktree", +} // EffectiveAccess is the access intent a runtime compiles: the layer-resolved // state when the spec went through ResolveSpecLayers, otherwise the spec's own diff --git a/pkg/api/access_compile.go b/pkg/api/access_compile.go index a12f43ed..b6a0447c 100644 --- a/pkg/api/access_compile.go +++ b/pkg/api/access_compile.go @@ -4,6 +4,8 @@ import ( "fmt" "maps" "strings" + + "github.com/flanksource/captain/pkg/codexhome" ) // AccessReport is what CompileAccess did for one runtime, for explain output, @@ -20,6 +22,9 @@ type AccessReport struct { Approval string `json:"approval,omitempty"` Mode PermissionMode `json:"mode,omitempty"` MCPDisabled bool `json:"mcpDisabled,omitempty"` + // ExecPolicy is how codex's execpolicy allow rules, which bypass the + // sandbox, are kept out of a read-only run. + ExecPolicy string `json:"execPolicy,omitempty"` // Overridden are authored settings the compiled posture replaced. Overridden []string `json:"overridden,omitempty"` // Equivalences are authored tool denies a runtime without a tool filter @@ -115,7 +120,7 @@ func compileToolsAccess(runtime Runtime, spec *Spec, state *AccessState, report denyAccessTools(spec, report, aliasCarriers(vocabulary, writeAliases)) report.Notes = append(report.Notes, "the sandbox confines Bash only, so edit and write tools are denied; Bash stays under the authored sandbox") default: - denyAccessTools(spec, report, append(aliasCarriers(vocabulary, readOnlyDeniedAliases), claudeSubAgentTools...)) + denyAccessTools(spec, report, append(aliasCarriers(vocabulary, readOnlyDeniedAliases), claudeOutOfProcessTools...)) spec.Permissions.MCP.Disabled = true report.MCPDisabled = true } @@ -158,10 +163,29 @@ func compileSandboxAccess(runtime Runtime, spec *Spec, state *AccessState, repor report.MCPDisabled = true } report.Sandbox, report.Approval = string(CodexSandboxReadOnly), string(CodexApprovalNever) + if report.ExecPolicy, err = codexExecPolicyMechanism(runtime); err != nil { + return err + } stripEnforcedDenies(runtime, spec, report, "enforced by the read-only sandbox") return nil } +// codexExecPolicyMechanism names how a read-only codex run keeps execpolicy +// allow rules out: they run a matching command outside the sandbox even under +// read-only with approval never. `codex exec` skips them with --ignore-rules; +// the app-server and the TUI have no such switch, so they start in captain's +// isolated CODEX_HOME, which has no rules (see pkg/codexhome). +func codexExecPolicyMechanism(runtime Runtime) (string, error) { + if runtime.Mode == ModeCLI { + return "user and project rules ignored (--ignore-rules)", nil + } + home, err := codexhome.ReadOnlyHome() + if err != nil { + return "", err + } + return fmt.Sprintf("isolated CODEX_HOME=%s without user rules; project rules that allow a command are refused", home), nil +} + // codexCLIArgsPosture reads cmux's raw codex flags. They bypass the sandbox // translation entirely, so they must already say read-only and never; anything // looser is refused rather than overridden behind the author's back. diff --git a/pkg/api/access_ginkgo_test.go b/pkg/api/access_ginkgo_test.go index f85890ce..b064f6e6 100644 --- a/pkg/api/access_ginkgo_test.go +++ b/pkg/api/access_ginkgo_test.go @@ -123,7 +123,9 @@ var _ = Describe("CompileAccess", func() { claudeAgent, explicitReadOnly(Spec{Sandbox: &SandboxRef{Mode: SandboxOff}}), Tools{"Bash": ToolPolicyDeny, "BashOutput": ToolPolicyDeny, "KillShell": ToolPolicyDeny, "Monitor": ToolPolicyDeny, "Edit": ToolPolicyDeny, "MultiEdit": ToolPolicyDeny, "NotebookEdit": ToolPolicyDeny, "Write": ToolPolicyDeny, - "Agent": ToolPolicyDeny, "Task": ToolPolicyDeny, "Workflow": ToolPolicyDeny}, + "Agent": ToolPolicyDeny, "Task": ToolPolicyDeny, "Workflow": ToolPolicyDeny, "TeamCreate": ToolPolicyDeny, "TeamDelete": ToolPolicyDeny, + "SendMessage": ToolPolicyDeny, "RemoteTrigger": ToolPolicyDeny, "CronCreate": ToolPolicyDeny, "CronDelete": ToolPolicyDeny, + "EnterWorktree": ToolPolicyDeny, "ExitWorktree": ToolPolicyDeny}, &SandboxRef{Mode: SandboxOff}, PermissionMode(""), true), Entry("claude: a tool-derived intent passes through untouched", claudeAgent, derived(Spec{Permissions: Permissions{Tools: readOnlyTools}}, AccessDialectTools, "permissions.tools"), @@ -165,6 +167,18 @@ var _ = Describe("CompileAccess", func() { "contradicts permissions.tools"), ) + It("denies every claude tool that acts outside the agent's own process, on every claude transport", func() { + for _, runtime := range []Runtime{claudeAgent, RuntimeOf(Anthropic, ModeCLI), RuntimeOf(Anthropic, ModeCmux)} { + p, _ := runtime.ModelProvider() + compiled, _, err := CompileAccess(runtime, explicitReadOnly(Spec{})) + Expect(err).NotTo(HaveOccurred()) + tools, ignored := compiled.Permissions.Tools.ForRuntime(p, runtime.Mode) + Expect(ignored).To(BeEmpty(), "every denied name must be one the runtime knows, or the deny is dropped") + Expect(tools.DenyList()).To(ContainElements("SendMessage", "RemoteTrigger", "CronCreate", "TeamCreate", "EnterWorktree")) + Expect(tools.DenyList()).NotTo(ContainElements("ListAgents", "CronList", "WebFetch", "WebSearch"), "reads stay allowed") + } + }) + It("never mutates the input spec", func() { input := derived(Spec{Permissions: Permissions{Tools: Tools{"edit": ToolPolicyDeny, "write": ToolPolicyDeny, "shell": ToolPolicyDeny, "Read": ToolPolicyAllow}}, Sandbox: &SandboxRef{Mode: SandboxNative, Policy: &NativeSandboxPolicy{Filesystem: &SandboxFilesystemPolicy{}}}}, @@ -191,6 +205,18 @@ var _ = Describe("CompileAccess", func() { )) }) + DescribeTable("reports how codex's execpolicy rules are kept out", + func(runtime Runtime, want string) { + GinkgoT().Setenv("XDG_CONFIG_HOME", "/config") + _, report, err := CompileAccess(runtime, explicitReadOnly(Spec{})) + Expect(err).NotTo(HaveOccurred()) + Expect(report.ExecPolicy).To(ContainSubstring(want)) + }, + Entry("codex exec ignores them", RuntimeOf(OpenAI, ModeCLI), "--ignore-rules"), + Entry("the app-server runs in the isolated home", codexAgent, "CODEX_HOME=/config/captain/codex-read-only"), + Entry("the cmux TUI runs in the isolated home", codexCmux, "CODEX_HOME=/config/captain/codex-read-only"), + ) + It("agrees with the matrix's codex cell and the sandbox translator", func() { compiled, _, err := CompileAccess(codexAgent, explicitReadOnly(Spec{})) Expect(err).NotTo(HaveOccurred()) diff --git a/pkg/api/agent_resources.go b/pkg/api/agent_resources.go index 9ca747b6..f2a13325 100644 --- a/pkg/api/agent_resources.go +++ b/pkg/api/agent_resources.go @@ -136,19 +136,27 @@ var agentTools = map[string][]AgentTool{ {Name: "AskUserQuestion", Group: "Interaction", Description: "Ask the user a question mid-run.", Default: ToolPolicyAuto}, {Name: "Bash", Group: "Shell", Description: "Run shell commands.", Default: ToolPolicyAsk, Aliases: []string{"shell"}}, {Name: "BashOutput", Group: "Shell", Description: "Read output from a background shell.", Default: ToolPolicyAuto, Aliases: []string{"shell"}}, + {Name: "CronCreate", Group: "Planning", Description: "Schedule a prompt to run on a cron schedule.", Default: ToolPolicyAsk}, + {Name: "CronDelete", Group: "Planning", Description: "Delete a scheduled prompt.", Default: ToolPolicyAsk}, + {Name: "CronList", Group: "Planning", Description: "List scheduled prompts.", Default: ToolPolicyAuto}, {Name: "DesignSync", Group: "Web", Description: "Sync with a design tool.", Default: ToolPolicyAsk}, {Name: "Edit", Group: "Files", Description: "Apply targeted file edits.", Default: ToolPolicyAuto, Aliases: []string{"edit"}}, {Name: "EnterPlanMode", Group: "Planning", Description: "Switch the run into plan mode.", Default: ToolPolicyAuto}, + {Name: "EnterWorktree", Group: "Files", Description: "Create a git worktree and move the session into it.", Default: ToolPolicyAsk}, {Name: "ExitPlanMode", Group: "Planning", Description: "Present the plan and leave plan mode.", Default: ToolPolicyAuto}, + {Name: "ExitWorktree", Group: "Files", Description: "Leave, and optionally remove, the session's git worktree.", Default: ToolPolicyAsk}, {Name: "Glob", Group: "Files", Description: "Find files by glob pattern.", Default: ToolPolicyAuto, Aliases: []string{"search"}}, {Name: "Grep", Group: "Files", Description: "Search file contents.", Default: ToolPolicyAuto, Aliases: []string{"search"}}, {Name: "KillShell", Group: "Shell", Description: "Stop a background shell.", Default: ToolPolicyAuto, Aliases: []string{"shell"}}, + {Name: "ListAgents", Group: "Agents", Description: "List other Claude sessions reachable as peers.", Default: ToolPolicyAuto}, {Name: "Monitor", Group: "Shell", Description: "Run a command and stream its output.", Default: ToolPolicyAsk, Aliases: []string{"shell"}}, {Name: "MultiEdit", Group: "Files", Description: "Apply several edits to one file.", Default: ToolPolicyAuto, Aliases: []string{"edit"}}, {Name: "NotebookEdit", Group: "Files", Description: "Edit a Jupyter notebook cell.", Default: ToolPolicyAuto, Aliases: []string{"edit", "write"}}, {Name: "PushNotification", Group: "Interaction", Description: "Send the user a push notification.", Default: ToolPolicyAsk}, {Name: "Read", Group: "Files", Description: "Read files from the workspace.", Default: ToolPolicyAuto, Aliases: []string{"read"}}, + {Name: "RemoteTrigger", Group: "Agents", Description: "Trigger a remote agent run.", Default: ToolPolicyAsk}, {Name: "ScheduleWakeup", Group: "Planning", Description: "Schedule the run to resume later.", Default: ToolPolicyAuto}, + {Name: "SendMessage", Group: "Agents", Description: "Send a message to another agent or a peer Claude session.", Default: ToolPolicyAsk}, {Name: "Skill", Group: "Skills", Description: "Invoke a skill.", Default: ToolPolicyAuto}, {Name: "Task", Group: "Agents", Description: "Spawn a sub-agent (older name for Agent).", Default: ToolPolicyAsk}, {Name: "TaskCreate", Group: "Planning", Description: "Add a task to the task list.", Default: ToolPolicyAuto, Aliases: []string{"todo"}}, @@ -157,6 +165,8 @@ var agentTools = map[string][]AgentTool{ {Name: "TaskOutput", Group: "Agents", Description: "Read output from a background task.", Default: ToolPolicyAuto}, {Name: "TaskStop", Group: "Agents", Description: "Stop a background task.", Default: ToolPolicyAuto}, {Name: "TaskUpdate", Group: "Planning", Description: "Update a task on the task list.", Default: ToolPolicyAuto, Aliases: []string{"todo"}}, + {Name: "TeamCreate", Group: "Agents", Description: "Create a team of collaborating agents.", Default: ToolPolicyAsk}, + {Name: "TeamDelete", Group: "Agents", Description: "Disband an agent team.", Default: ToolPolicyAsk}, {Name: "TodoWrite", Group: "Planning", Description: "Track task progress.", Default: ToolPolicyAuto, Aliases: []string{"todo"}}, {Name: "ToolSearch", Group: "Interaction", Description: "Load deferred tool definitions.", Default: ToolPolicyAuto}, {Name: "WebFetch", Group: "Web", Description: "Fetch a web page.", Default: ToolPolicyAsk, Aliases: []string{"web_fetch"}}, diff --git a/pkg/api/permission_capabilities.go b/pkg/api/permission_capabilities.go index 861a6335..bec5189b 100644 --- a/pkg/api/permission_capabilities.go +++ b/pkg/api/permission_capabilities.go @@ -352,7 +352,8 @@ func apiAccess() map[AccessLevel]Support { // claudeAccess: the tool dialect, compiled to per-tool denies. func claudeAccess() map[AccessLevel]Support { return access(nativeNote("--disallowedTools", - "denies every edit, write and shell carrier plus Agent, Task and Workflow, and disables third-party MCP servers")) + "denies every edit, write and shell carrier plus the tools that act outside the agent's process (sub-agents and teams, "+ + "SendMessage to peer sessions, RemoteTrigger, CronCreate/CronDelete, Enter/ExitWorktree), and disables third-party MCP servers")) } // codexAccess: the sandbox dialect. Codex reads through its shell, so the shell @@ -361,7 +362,8 @@ func claudeAccess() map[AccessLevel]Support { func codexAccess() map[AccessLevel]Support { return access(Support{Kind: SupportNative, Effects: PermissionEffects{ Sandbox: string(CodexSandboxReadOnly), Approval: string(CodexApprovalNever), - Note: "the shell stays as codex's read path, confined by the read-only sandbox; third-party MCP servers are disabled", + Note: "the shell stays as codex's read path, confined by the read-only sandbox; third-party MCP servers are disabled; " + + "execpolicy allow rules, which run commands outside the sandbox, are kept out with --ignore-rules on exec and an isolated CODEX_HOME on the app-server and cmux", }}) } diff --git a/pkg/cli/permissions_access.go b/pkg/cli/permissions_access.go index 155288a0..4dee13a1 100644 --- a/pkg/cli/permissions_access.go +++ b/pkg/cli/permissions_access.go @@ -141,6 +141,7 @@ func reportLines(report api.AccessReport) []string { if report.MCPDisabled { lines = append(lines, "mcp: disabled") } + add("exec policy", report.ExecPolicy) add("overridden", report.Overridden...) add("equivalent", report.Equivalences...) add("note", report.Notes...) diff --git a/pkg/cli/permissions_access_ginkgo_test.go b/pkg/cli/permissions_access_ginkgo_test.go index 62151a70..aa0e15cf 100644 --- a/pkg/cli/permissions_access_ginkgo_test.go +++ b/pkg/cli/permissions_access_ginkgo_test.go @@ -70,6 +70,7 @@ var _ = Describe("captain permissions explain", func() { Expect(codex.Runtime).To(Equal("openai agent")) Expect(codex.Report.Sandbox).To(Equal("read-only")) Expect(codex.Report.Approval).To(Equal("never")) + Expect(codex.Report.ExecPolicy).To(ContainSubstring("isolated CODEX_HOME=")) Expect(result.Suggestion.Reason).To(Equal("permissions.access is already read-only")) }) }) From b0fdf93c76abd51eb0ab48b1d58fbadffe7cb779 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Thu, 22 Oct 2026 22:55:52 +0300 Subject: [PATCH 14/77] feat(prompt): add lookup locations and per-command help to prompt CLI Append the prompt source search paths to human-readable output of prompt list, so users can see where prompts are loaded from. JSON, YAML, and file exports are unchanged. Replace the shared help for prompt subcommands with command-specific help that includes descriptions, examples, and usage. The root prompt help gains a Help and output section covering color, NO_COLOR, --json, and agent-session Markdown. The help text now states that permissions.tools 'ask' is not enforced by native tool filters and that per-call approval goes through the broker. The sample prompt's Edit tool policy changes from ask to allow to match this. --- cmd/captain/main.go | 4 ++ pkg/cli/prompt_help.go | 24 +++++--- pkg/cli/prompt_help_commands.go | 67 ++++++++++++++++++++ pkg/cli/prompt_help_content.go | 6 +- pkg/cli/prompt_help_ginkgo_test.go | 76 +++++++++++++++++++++++ pkg/cli/prompt_list.go | 76 +++++++++++++++++++++++ pkg/cli/prompt_list_ginkgo_test.go | 98 ++++++++++++++++++++++++++++++ 7 files changed, 340 insertions(+), 11 deletions(-) create mode 100644 pkg/cli/prompt_help_commands.go create mode 100644 pkg/cli/prompt_list.go create mode 100644 pkg/cli/prompt_list_ginkgo_test.go diff --git a/cmd/captain/main.go b/cmd/captain/main.go index 1e07b344..c1e4c0be 100644 --- a/cmd/captain/main.go +++ b/cmd/captain/main.go @@ -367,6 +367,10 @@ func newRootCommand() *cobra.Command { cli.RegisterRuntimeEntities() cli.RegisterBudgetEntities() clicky.GenerateCLI(rootCmd) + if err := cli.AttachPromptListOutput(rootCmd); err != nil { + fmt.Fprintf(os.Stderr, "failed to attach prompt list output: %v\n", err) + os.Exit(1) + } if err := cli.AttachPromptSchemaFlag(rootCmd); err != nil { fmt.Fprintf(os.Stderr, "failed to attach prompt schema flag: %v\n", err) os.Exit(1) diff --git a/pkg/cli/prompt_help.go b/pkg/cli/prompt_help.go index 55012e60..ede75884 100644 --- a/pkg/cli/prompt_help.go +++ b/pkg/cli/prompt_help.go @@ -15,8 +15,7 @@ type promptHelpRenderOptions struct { NoColor bool } -// AttachPromptHelp replaces the generated prompt root help while preserving -// the generated help for its list, CRUD, render, and run subcommands. +// AttachPromptHelp documents the prompt tree using the same terminal and agent formats. func AttachPromptHelp(root *cobra.Command) error { promptCmd, _, err := root.Find([]string{"prompt"}) if err != nil { @@ -26,12 +25,7 @@ func AttachPromptHelp(root *cobra.Command) error { return fmt.Errorf("find prompt command: got %v", promptCmd) } - defaultHelp := promptCmd.HelpFunc() - promptCmd.SetHelpFunc(func(cmd *cobra.Command, args []string) { - if cmd != promptCmd { - defaultHelp(cmd, args) - return - } + promptCmd.SetHelpFunc(func(cmd *cobra.Command, _ []string) { opts := promptHelpRenderOptions{ LLMSession: CurrentEnvironmentSession() != nil, NoColor: clicky.Flags.NoColor, @@ -51,7 +45,11 @@ func renderPromptHelp(cmd *cobra.Command, opts promptHelpRenderOptions) (string, } formatOpts := clicky.FormatOptions{Format: format, NoColor: opts.NoColor} formatOpts.ResolveNoColor() - out, err := clicky.Format(promptHelpGuide(cmd, !opts.LLMSession), formatOpts) + guide := promptHelpGuide + if cmd.Name() != "prompt" { + guide = promptCommandHelpGuide + } + out, err := clicky.Format(guide(cmd, !opts.LLMSession), formatOpts) if err != nil { return "", fmt.Errorf("format prompt help as %s: %w", format, err) } @@ -78,6 +76,7 @@ func promptHelpGuide(cmd *cobra.Command, styled bool) api.Text { NewLine().NewLine(). Add(promptHelpHeading("Start here", styled)).NewLine(). Add(promptHelpBullets(styled, + "Discover available prompts: captain prompt list; inspect one: captain prompt get ", "Validate and inspect a rendered file without calling a model: captain prompt render ", "Execute it: captain prompt run ", "Print the generated JSON schemas, catalogs, enum values, and backend-specific cliArgs: captain prompt --schema", @@ -115,6 +114,13 @@ func promptHelpGuide(cmd *cobra.Command, styled bool) api.Text { "Use runtimes[] for prompt-owned parallel defaults, or repeat -M/--multi-models at execution time to compare explicit runtime targets.", )). NewLine().NewLine(). + Add(promptHelpHeading("Help and output", styled)).NewLine(). + Add(promptHelpBullets(styled, + "Use captain prompt --help for examples and the complete generated flag reference.", + "Human terminal help uses color; --no-color or NO_COLOR disables it. Redirected output is uncolored. Detected agent sessions receive Markdown without ANSI escapes.", + "Use --json for structured command results, --no-stream for a buffered run, or captain prompt observe for one observation JSON document.", + )). + NewLine().NewLine(). Add(promptHelpHeading("Command usage", styled)).NewLine(). Add(clicky.CodeBlock("text", strings.TrimSpace(cmd.UsageString()))) return doc diff --git a/pkg/cli/prompt_help_commands.go b/pkg/cli/prompt_help_commands.go new file mode 100644 index 00000000..da75ac35 --- /dev/null +++ b/pkg/cli/prompt_help_commands.go @@ -0,0 +1,67 @@ +package cli + +import ( + "strings" + + "github.com/flanksource/clicky" + "github.com/flanksource/clicky/api" + "github.com/spf13/cobra" +) + +func promptCommandHelpGuide(cmd *cobra.Command, styled bool) api.Text { + doc := api.Text{}. + Add(clicky.Heading(1, promptHelpText(cmd.CommandPath(), styled, "font-bold text-blue-600"))). + NewLine().NewLine(). + Add(clicky.Text(cmd.Short)) + if cmd.Long != "" && cmd.Long != cmd.Short { + doc = doc.NewLine().NewLine().Add(clicky.Text(cmd.Long)) + } + if help, ok := promptCommandHelp[cmd.Name()]; ok { + doc = doc.NewLine().NewLine().Add(clicky.Text(help.Description)). + NewLine().NewLine().Add(promptHelpHeading("Examples", styled)).NewLine(). + Add(clicky.CodeBlock("bash", help.Examples)) + } + return doc.NewLine().NewLine(). + Add(promptHelpHeading("Command usage and flags", styled)).NewLine(). + Add(clicky.CodeBlock("text", strings.TrimSpace(cmd.UsageString()))). + NewLine().NewLine(). + Add(clicky.Text("See captain prompt --help for file format, variables, runtime fields, and source selection. Use --no-color for plain help; detected agent sessions receive Markdown.")) +} + +var promptCommandHelp = map[string]struct { + Description string + Examples string +}{ + "list": { + Description: "Discover embedded, built-in, configured, project and user prompts. Filter by name, description, model or path with --query, and by source with --source. Local files shadow embedded prompts of the same name.", + Examples: "captain prompt list\ncaptain prompt list --query review --source local\ncaptain prompt list --json", + }, + "get": { + Description: "Inspect a prompt's raw content, variables, schemas and version. Accepts a catalog ID, bare name or .prompt path. Invalid files remain readable with parseError so they can be repaired.", + Examples: "captain prompt get proposal-review\ncaptain prompt get .captain/prompts/review.prompt --json", + }, + "create": { + Description: "Create a local .prompt file from content. Choose a writable source with target and a relative destination with relPath or name. Embedded prompts are read-only; create a local copy to customize one. Content is validated before writing.", + Examples: `captain prompt create name=hello 'content=Hello {{name}}'`, + }, + "update": { + Description: "Replace a writable prompt's content after validation. Send the version returned by get as baseVersion to detect concurrent edits. Updating an embedded prompt is refused; create a local copy instead.", + Examples: `captain prompt update .captain/prompts/hello.prompt 'content=Hello {{name}}!' baseVersion=VERSION_FROM_GET`, + }, + "delete": { + Description: "Delete a writable local prompt file. Embedded and built-in prompts cannot be deleted. Removing a local override exposes the embedded prompt again.", + Examples: "captain prompt delete .captain/prompts/hello.prompt", + }, + "render": { + Description: "Preview the rendered messages, complete input spec, schemas and resolution trace without calling a model or running setup. Inspect validationError before execution. --preset replaces frontmatter presets; --no-presets clears them.", + Examples: "captain prompt render review.prompt -V target=pkg/cli --json\ncaptain prompt render --model agent:sonnet -p 'Explain {{topic}}' -V topic=permissions\ngit diff | captain prompt render review.prompt -V patch=- --json", + }, + "run": { + Description: "Render, validate and execute a prompt. Supply one positional source, inline --prompt/-p, or stdin. Inline text is literal unless variables or {{input}} enable templating. Repeat -M for parallel runtimes. Foreground single-runtime agent runs can broker questions when stdin and stderr are terminals.", + Examples: "captain prompt run --model agent:sonnet -p 'Explain this repository'\ncaptain prompt run review.prompt -V target=pkg/cli --access read-only\ngit diff | captain prompt run review.prompt -V patch=-\ncaptain prompt run review.prompt -M agent:sonnet -M agent:gpt-6.1-sol\ncaptain prompt run review.prompt --no-stream --json", + }, + "observe": { + Description: "Execute exactly one --runtime and emit a captain.observation/v1 JSON document for profiling and evaluation. This CLI-only action refuses --model, --mode, fallbacks, parallel matrices and workflow-backed prompts. Optional --mcp-config and --capture-kubernetes flags capture external tool traffic.", + Examples: "captain prompt observe --runtime agent:sonnet -p 'Summarize this repository'", + }, +} diff --git a/pkg/cli/prompt_help_content.go b/pkg/cli/prompt_help_content.go index 7f8f3241..3ba27e57 100644 --- a/pkg/cli/prompt_help_content.go +++ b/pkg/cli/prompt_help_content.go @@ -43,7 +43,7 @@ permissions: mode: acceptEdits tools: Read: allow - Edit: ask + Edit: allow memory: skipUser: true setup: @@ -63,6 +63,7 @@ Summarize this change: func promptDotpromptHelpFields() []promptHelpField { return []promptHelpField{ + {"presets[]", "Runtime preset ids or names selected beneath this prompt; --preset replaces the selection and --no-presets clears it. Explicit order controls final layer precedence."}, {"name, description", "Human-readable prompt catalog metadata."}, {"model", "Default model selector. Compact selectors may include runtime mode and effort, for example agent:sonnet:high."}, {"config.maxOutputTokens", "Maximum output tokens for each model call; takes precedence over budget.maxTokens when both are present."}, @@ -104,8 +105,9 @@ func promptSpecHelpFields() []promptHelpField { {"memory.skipSkills, memory.skipHooks, memory.skipMemory", "Disable skills, hooks, or auto-memory/agent instruction files."}, {"memory.bare", "Skip hooks, skills, memory, and ambient settings together."}, {"permissions.mode", "Permission posture, independent of the sandbox: default, plan, acceptEdits, auto, bypassPermissions, or dontAsk."}, + {"permissions.access", "Portable read-only or full access intent, compiled into the selected runtime's native restrictions. Caller tools remain governed by toolPreferences."}, {"permissions.presets[]", "Named safety bundles: edit or bare."}, - {"permissions.tools.", "Per-tool policy: auto, ask, allow, or deny. Captain fails if the selected runtime cannot enforce it."}, + {"permissions.tools.", "Declarative tool filter: auto, allow, or deny. ask cannot be enforced by native tool filters; per-call approval uses the broker. Unsupported restrictions fail before dispatch."}, {"permissions.mcp.disabled", "Disable all MCP servers."}, {"permissions.mcp.servers[]", "Optional allowlist of configured MCP servers."}, {"permissions.mcp.", "Enable or disable one configured MCP server."}, diff --git a/pkg/cli/prompt_help_ginkgo_test.go b/pkg/cli/prompt_help_ginkgo_test.go index ca13fad9..841ca301 100644 --- a/pkg/cli/prompt_help_ginkgo_test.go +++ b/pkg/cli/prompt_help_ginkgo_test.go @@ -11,6 +11,12 @@ import ( ) var _ = Describe("prompt help", func() { + BeforeEach(func() { + GinkgoT().Setenv("CLICKY_FORCE_INTERACTIVE", "1") + GinkgoT().Setenv("NO_COLOR", "") + GinkgoT().Setenv("TERM", "xterm-256color") + GinkgoT().Setenv("COLOR", "") + }) clearSessionMarkers := func() { for _, marker := range []string{ "CODEX_THREAD_ID", "CODEX_SESSION_ID", "CODEX_SANDBOX", @@ -49,6 +55,27 @@ var _ = Describe("prompt help", func() { Expect(output).NotTo(ContainSubstring("\x1b[")) }) + DescribeTable("honors plain help output", func(name, reason string) { + switch reason { + case "environment": + GinkgoT().Setenv("NO_COLOR", "1") + case "redirected": + GinkgoT().Setenv("CLICKY_FORCE_INTERACTIVE", "") + } + output, err := renderPromptHelp(&cobra.Command{Use: name}, promptHelpRenderOptions{NoColor: reason == "flag"}) + + Expect(err).NotTo(HaveOccurred()) + Expect(output).NotTo(BeEmpty()) + Expect(output).NotTo(ContainSubstring("\x1b[")) + }, + Entry("root flag", "prompt", "flag"), + Entry("root environment", "prompt", "environment"), + Entry("root redirected", "prompt", "redirected"), + Entry("child flag", "run", "flag"), + Entry("child environment", "run", "environment"), + Entry("child redirected", "run", "redirected"), + ) + It("documents the complete prompt-file authoring contract", func() { output, err := renderPromptHelp(promptCommand(), promptHelpRenderOptions{LLMSession: true}) @@ -65,6 +92,10 @@ var _ = Describe("prompt help", func() { "fallbacks[]", "prompt.schemaStrictness", "permissions.tools.", + "permissions.access", + "presets[]", + "--no-color", + "captain prompt observe", "permissions.mcp.", "memory.skipProject", "setup.checkout.worktree.uncommitted", @@ -99,4 +130,49 @@ var _ = Describe("prompt help", func() { Expect(output.String()).NotTo(ContainSubstring("\x1b[")) Expect(output.String()).NotTo(ContainSubstring("style=")) }) + + DescribeTable("renders help throughout the prompt command tree", func(name string, llm, noColor bool) { + clearSessionMarkers() + if llm { + GinkgoT().Setenv("CODEX_THREAD_ID", "thread-example") + } + previous := clicky.Flags.NoColor + DeferCleanup(func() { clicky.Flags.NoColor = previous }) + clicky.Flags.NoColor = noColor + root := &cobra.Command{Use: "captain"} + prompt := promptCommand() + child := &cobra.Command{Use: name + " [id]", Short: "Manage " + name, Run: func(*cobra.Command, []string) {}} + child.Flags().String("query", "", "Filter by name") + prompt.AddCommand(child) + root.AddCommand(prompt) + Expect(AttachPromptHelp(root)).To(Succeed()) + var output bytes.Buffer + root.SetOut(&output) + root.SetArgs([]string{"prompt", name, "--help"}) + + Expect(root.Execute()).To(Succeed()) + Expect(output.String()).To(ContainSubstring("captain prompt " + name)) + Expect(output.String()).To(ContainSubstring("--query")) + Expect(output.String()).NotTo(ContainSubstring("Captain .prompt Files")) + if llm { + Expect(output.String()).To(HavePrefix("# captain prompt " + name)) + } + if llm || noColor { + Expect(output.String()).NotTo(ContainSubstring("\x1b[")) + } else { + Expect(output.String()).To(ContainSubstring("\x1b[")) + Expect(output.String()).To(ContainSubstring("38;2;")) + } + }, + Entry("run on a terminal", "run", false, false), + Entry("render on a terminal", "render", false, false), + Entry("list on a terminal", "list", false, false), + Entry("get on a terminal", "get", false, false), + Entry("create on a terminal", "create", false, false), + Entry("update on a terminal", "update", false, false), + Entry("delete on a terminal", "delete", false, false), + Entry("observe on a terminal", "observe", false, false), + Entry("run in an agent session", "run", true, false), + Entry("render without color", "render", false, true), + ) }) diff --git a/pkg/cli/prompt_list.go b/pkg/cli/prompt_list.go new file mode 100644 index 00000000..cb21ab3f --- /dev/null +++ b/pkg/cli/prompt_list.go @@ -0,0 +1,76 @@ +package cli + +import ( + "context" + "fmt" + "io" + "strings" + + "github.com/flanksource/clicky" + "github.com/spf13/cobra" +) + +// AttachPromptListOutput adds lookup locations to the generated prompt list. +func AttachPromptListOutput(root *cobra.Command) error { + prompt, _, err := root.Find([]string{"prompt"}) + if err != nil || prompt == nil || prompt.Name() != "prompt" { + return fmt.Errorf("prompt list output requires a generated prompt command") + } + list, _, err := prompt.Find([]string{"list"}) + if err != nil || list == nil || list.Name() != "list" { + return fmt.Errorf("prompt list output requires a generated list command") + } + for _, cmd := range []*cobra.Command{prompt, list} { + run := cmd.RunE + if run == nil { + return fmt.Errorf("prompt list output requires a handler for %s", cmd.CommandPath()) + } + cmd.RunE = func(cmd *cobra.Command, args []string) error { + footer, err := promptLookupFooter(cmd.Context(), clicky.Flags.FormatOptions) + if err != nil { + return err + } + if err := run(cmd, args); err != nil { + return err + } + _, err = io.WriteString(cmd.OutOrStdout(), footer) + return err + } + } + return nil +} + +func promptLookupFooter(ctx context.Context, opts clicky.FormatOptions) (string, error) { + if err := opts.ParseFormatSpec(); err != nil { + return "", err + } + format := "pretty" + if len(opts.Sinks) > 0 { + format = "" + for _, sink := range opts.Sinks { + if sink.File == "" { + format = sink.Format + } + } + } + if format != "pretty" && format != "markdown" { + return "", nil + } + sources, err := buildPromptSources(ctx, promptSourceOptions{}) + if err != nil { + return "", err + } + text := clicky.Text("").Add(clicky.Text("Lookup locations", "font-bold")) + for _, source := range sources { + location := source.Root + if source.Kind == "embedded" { + location = fmt.Sprintf("embedded: %s/ (%s)", source.WalkRoot, source.Label) + } + text = text.NewLine().Append(" - ").Append(location) + } + out, err := clicky.Format(text, clicky.FormatOptions{Format: format, NoColor: opts.NoColor}) + if err != nil { + return "", err + } + return "\n" + strings.TrimRight(out, "\n") + "\n", nil +} diff --git a/pkg/cli/prompt_list_ginkgo_test.go b/pkg/cli/prompt_list_ginkgo_test.go new file mode 100644 index 00000000..768ba1fb --- /dev/null +++ b/pkg/cli/prompt_list_ginkgo_test.go @@ -0,0 +1,98 @@ +package cli + +import ( + "bytes" + "context" + "errors" + "os" + "path/filepath" + + "github.com/flanksource/captain/pkg/captainconfig" + "github.com/flanksource/clicky" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" + "github.com/spf13/cobra" +) + +var _ = Describe("Prompt list lookup locations", func() { + BeforeEach(func() { + captainconfig.SetPathForTesting(filepath.Join(GinkgoT().TempDir(), ".captain.yaml")) + DeferCleanup(captainconfig.SetPathForTesting, "") + GinkgoT().Setenv("XDG_CONFIG_HOME", GinkgoT().TempDir()) + GinkgoT().Chdir(GinkgoT().TempDir()) + }) + + It("shows embedded sources and nonexistent project and user lookup directories", func() { + cwd, err := filepath.Abs(".") + Expect(err).NotTo(HaveOccurred()) + home, err := captainconfig.Home() + Expect(err).NotTo(HaveOccurred()) + out, err := promptLookupFooter(context.Background(), clicky.FormatOptions{NoColor: true}) + Expect(err).NotTo(HaveOccurred()) + Expect(out).To(ContainSubstring("Lookup locations")) + Expect(out).To(ContainSubstring("Built-in prompts")) + Expect(out).To(ContainSubstring("Embedded examples")) + Expect(out).To(ContainSubstring(filepath.Join(cwd, ".captain", "prompts"))) + Expect(out).To(ContainSubstring(filepath.Join(home, "prompts"))) + }) + + It("shows configured and host sources instead of an inactive project fallback", func() { + configPath, err := captainconfig.Path() + Expect(err).NotTo(HaveOccurred()) + Expect(os.Mkdir(filepath.Join(filepath.Dir(configPath), "configured-prompts"), 0o700)).To(Succeed()) + Expect(os.Mkdir("host-prompts", 0o700)).To(Succeed()) + Expect(captainconfig.Save(captainconfig.Config{Prompts: captainconfig.PromptDefaults{Dirs: []string{"configured-prompts"}}})).To(Succeed()) + ctx := ContextWithPromptSources(context.Background(), PromptSources{Dirs: []string{"host-prompts"}}) + out, err := promptLookupFooter(ctx, clicky.FormatOptions{Format: "markdown"}) + Expect(err).NotTo(HaveOccurred()) + Expect(out).To(ContainSubstring("**Lookup locations**")) + Expect(out).To(ContainSubstring(filepath.Join(filepath.Dir(configPath), "configured-prompts"))) + Expect(out).To(ContainSubstring("host-prompts")) + Expect(out).NotTo(ContainSubstring(filepath.Join(".captain", "prompts"))) + }) + + DescribeTable("keeps machine output and file exports free of a terminal footer", func(opts clicky.FormatOptions) { + out, err := promptLookupFooter(context.Background(), opts) + Expect(err).NotTo(HaveOccurred()) + Expect(out).To(BeEmpty()) + }, + Entry("JSON", clicky.FormatOptions{JSON: true}), + Entry("YAML", clicky.FormatOptions{YAML: true}), + Entry("JSON with Markdown artifact", clicky.FormatOptions{Format: "json,markdown=report.md"}), + Entry("file output", clicky.FormatOptions{Format: "pretty", Output: "report.txt"}), + ) + + DescribeTable("appends locations to the generated list and its root alias only after success", func(child bool, runErr error) { + previous := clicky.Flags.FormatOptions + DeferCleanup(func() { clicky.Flags.FormatOptions = previous }) + clicky.Flags.FormatOptions = clicky.FormatOptions{NoColor: true} + root := &cobra.Command{Use: "captain"} + var out bytes.Buffer + root.SetOut(&out) + run := func(cmd *cobra.Command, _ []string) error { + cmd.Print("prompt rows\n") + return runErr + } + prompt := &cobra.Command{Use: "prompt", RunE: run} + list := &cobra.Command{Use: "list", RunE: run} + prompt.AddCommand(list) + root.AddCommand(prompt) + Expect(AttachPromptListOutput(root)).To(Succeed()) + target := prompt + if child { + target = list + } + err := target.RunE(target, nil) + if runErr == nil { + Expect(err).NotTo(HaveOccurred()) + Expect(out.String()).To(MatchRegexp("(?s)prompt rows.*Lookup locations")) + } else { + Expect(err).To(MatchError(runErr)) + Expect(out.String()).To(Equal("prompt rows\n")) + } + }, + Entry("list command", true, nil), + Entry("root alias", false, nil), + Entry("failed list", true, errors.New("cannot list prompts")), + ) +}) From 9502f8ac0d6b66b56b30f4ec34494ee709f75164 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Thu, 22 Oct 2026 22:55:56 +0300 Subject: [PATCH 15/77] fix(monitor): Ingest codex rollouts written to captain's read-only home Read-only codex runs write rollouts under captain's isolated CODEX_HOME, which the monitor did not watch or accept, so those transcripts were never ingested. Watch day directories and resolve threads across both codex session roots. Accept transcript paths under any provider root, and validate ingest paths against all of them. --- pkg/monitor/hooks.go | 60 ++++++++++++++++++++++++--------------- pkg/monitor/hooks_test.go | 21 +++++++++++++- pkg/monitor/ingest.go | 16 ++++------- pkg/monitor/process.go | 25 ++++++++++++---- 4 files changed, 82 insertions(+), 40 deletions(-) diff --git a/pkg/monitor/hooks.go b/pkg/monitor/hooks.go index 4fcafc4b..ae304c66 100644 --- a/pkg/monitor/hooks.go +++ b/pkg/monitor/hooks.go @@ -11,6 +11,7 @@ import ( "github.com/flanksource/captain/pkg/ai/history" "github.com/flanksource/captain/pkg/api" "github.com/flanksource/captain/pkg/claude" + "github.com/flanksource/captain/pkg/codexhome" "github.com/flanksource/captain/pkg/database" ) @@ -65,7 +66,7 @@ func (m *Monitor) handleHookEvent(ctx context.Context, watcher *transcriptWatche // The rollout may not be flushed yet; arm today's day dir so the // eventual write is tailed, and let recon cover the rest. log.Debugf("hook codex/%s: no rollout found for thread %s yet", ev.Event, ev.SessionID) - watcher.watchDir(codexDayDir(time.Now()), "codex") + watchCodexDayDirs(watcher, time.Now()) return } } @@ -181,28 +182,40 @@ func (m *Monitor) endHookSessionProcesses(ctx context.Context, ev HookEvent) { // returns false so an untrusted hook can never point ingestion at an arbitrary // file. func withinHookRoot(provider, cleanPath string) bool { - root, err := hookTranscriptRoot(provider) - if err != nil || root == "" { - return false - } - return strings.HasPrefix(cleanPath, root+string(filepath.Separator)) + root, err := hookTranscriptRootOf(provider, cleanPath) + return err == nil && root != "" } -func hookTranscriptRoot(provider string) (string, error) { +// hookTranscriptRoots are the session roots a provider writes transcripts +// under. Codex has two: the user's home and the isolated home captain starts +// read-only runs in. +func hookTranscriptRoots(provider string) ([]string, error) { switch provider { case "claude": - return claude.GetProjectsDir(), nil + return []string{claude.GetProjectsDir()}, nil case "codex": - home, err := os.UserHomeDir() - if err != nil { - return "", err - } - return filepath.Join(home, ".codex", "sessions"), nil + return codexhome.SessionRoots() case api.TranscriptSourceAPI: - return history.APITranscriptRoot() + root, err := history.APITranscriptRoot() + return []string{root}, err default: - return "", fmt.Errorf("unknown hook provider %q", provider) + return nil, fmt.Errorf("unknown hook provider %q", provider) + } +} + +// hookTranscriptRootOf is the provider root that contains path, or "" when +// none does. +func hookTranscriptRootOf(provider, path string) (string, error) { + roots, err := hookTranscriptRoots(provider) + if err != nil { + return "", err + } + for _, root := range roots { + if root != "" && strings.HasPrefix(path, root+string(filepath.Separator)) { + return root, nil + } } + return "", nil } // resolveCodexTranscript finds the rollout file for a codex thread id. The @@ -216,14 +229,15 @@ func resolveCodexTranscript(threadID string) string { suffix := "-" + threadID + ".jsonl" now := time.Now() for _, day := range []time.Time{now, now.AddDate(0, 0, -1)} { - dir := codexDayDir(day) - entries, err := os.ReadDir(dir) - if err != nil { - continue - } - for _, entry := range entries { - if strings.HasSuffix(entry.Name(), suffix) { - return filepath.Join(dir, entry.Name()) + for _, dir := range codexDayDirs(day) { + entries, err := os.ReadDir(dir) + if err != nil { + continue + } + for _, entry := range entries { + if strings.HasSuffix(entry.Name(), suffix) { + return filepath.Join(dir, entry.Name()) + } } } } diff --git a/pkg/monitor/hooks_test.go b/pkg/monitor/hooks_test.go index 3393e007..2cc082f3 100644 --- a/pkg/monitor/hooks_test.go +++ b/pkg/monitor/hooks_test.go @@ -50,9 +50,13 @@ func TestStatusLineDoesNotCountAsActivity(t *testing.T) { func TestWithinHookRoot(t *testing.T) { home := t.TempDir() t.Setenv("HOME", home) + t.Setenv("CODEX_HOME", "") + t.Setenv("XDG_CONFIG_HOME", "") claudePath := filepath.Clean(filepath.Join(home, ".claude", "projects", "-repo", "s.jsonl")) codexPath := filepath.Clean(filepath.Join(home, ".codex", "sessions", "2026", "07", "14", "rollout-x.jsonl")) + readOnlyPath := filepath.Clean(filepath.Join(home, ".config", "captain", "codex-read-only", "sessions", "2026", "07", "14", "rollout-y.jsonl")) + assert.True(t, withinHookRoot("codex", readOnlyPath), "a read-only run's rollout in captain's isolated CODEX_HOME is accepted") traversal := filepath.Clean(filepath.Join(home, ".claude", "projects", "..", "..", "secret.jsonl")) assert.True(t, withinHookRoot("claude", claudePath), "claude transcript under the projects root is accepted") @@ -64,16 +68,31 @@ func TestWithinHookRoot(t *testing.T) { assert.False(t, withinHookRoot("gemini", claudePath), "unknown provider is rejected") } +func TestCodexDayDirsCoverTheReadOnlyHome(t *testing.T) { + home := t.TempDir() + t.Setenv("HOME", home) + t.Setenv("CODEX_HOME", "") + t.Setenv("XDG_CONFIG_HOME", "") + day := time.Date(2026, 10, 22, 12, 0, 0, 0, time.UTC) + + assert.Equal(t, []string{ + filepath.Join(home, ".codex", "sessions", "2026", "10", "22"), + filepath.Join(home, ".config", "captain", "codex-read-only", "sessions", "2026", "10", "22"), + }, codexDayDirs(day), "a read-only run's rollout is written under captain's isolated CODEX_HOME") +} + func TestResolveCodexTranscript(t *testing.T) { home := t.TempDir() t.Setenv("HOME", home) + t.Setenv("CODEX_HOME", "") + t.Setenv("XDG_CONFIG_HOME", "") threadID := "0195c1de-4ab8-7000-8000-0123456789ab" assert.Empty(t, resolveCodexTranscript(threadID), "no sessions dir yet") assert.Empty(t, resolveCodexTranscript(""), "empty thread id") writeRollout := func(day time.Time, name string) string { - dir := codexDayDir(day) + dir := codexDayDirs(day)[0] require.NoError(t, os.MkdirAll(dir, 0o755)) path := filepath.Join(dir, name) require.NoError(t, os.WriteFile(path, []byte("{}\n"), 0o644)) diff --git a/pkg/monitor/ingest.go b/pkg/monitor/ingest.go index 11a8810b..f1bd9a7f 100644 --- a/pkg/monitor/ingest.go +++ b/pkg/monitor/ingest.go @@ -212,20 +212,16 @@ func (ing *ingestor) needsIngest(path string, info os.FileInfo) bool { // child sessions of the root transcript's session; root ingests also arm the // watcher on the session's subagents directory. func (ing *ingestor) ingestFile(ctx context.Context, source, path string) error { - root, err := hookTranscriptRoot(source) + path, err := filepath.Abs(path) if err != nil { - return err - } - root, err = filepath.Abs(root) - if err != nil { - return fmt.Errorf("resolve %s transcript root: %w", source, err) + return fmt.Errorf("resolve %s transcript path: %w", source, err) } - path, err = filepath.Abs(path) + root, err := hookTranscriptRootOf(source, path) if err != nil { - return fmt.Errorf("resolve %s transcript path: %w", source, err) + return err } - if !strings.HasPrefix(path, root+string(filepath.Separator)) { - return fmt.Errorf("transcript path %s is outside the %s session root", path, source) + if root == "" { + return fmt.Errorf("transcript path %s is outside every %s session root", path, source) } rootFS, err := os.OpenRoot(root) if err != nil { diff --git a/pkg/monitor/process.go b/pkg/monitor/process.go index 71404d7d..56c07491 100644 --- a/pkg/monitor/process.go +++ b/pkg/monitor/process.go @@ -2,12 +2,12 @@ package monitor import ( "context" - "os" "path/filepath" "strconv" "time" "github.com/flanksource/captain/pkg/claude" + "github.com/flanksource/captain/pkg/codexhome" "github.com/flanksource/captain/pkg/database" sessionprocess "github.com/flanksource/captain/pkg/session/process" "github.com/google/uuid" @@ -181,7 +181,7 @@ func (m *Monitor) watchLiveSession(ctx context.Context, watcher *transcriptWatch watcher.watchDir(filepath.Join(claude.GetProjectsDir(), claude.NormalizePath(proc.CWD)), "claude") } case "codex": - watcher.watchDir(codexDayDir(time.Now()), "codex") + watchCodexDayDirs(watcher, time.Now()) } path := m.samples.sessionPath(sessionID) if path == "" { @@ -195,12 +195,25 @@ func (m *Monitor) watchLiveSession(ctx context.Context, watcher *transcriptWatch } } -func codexDayDir(now time.Time) string { - home, err := os.UserHomeDir() +// codexDayDirs are codex's per-day rollout directories for now under every +// home it writes to: the user's and captain's isolated read-only home. +func codexDayDirs(now time.Time) []string { + roots, err := codexhome.SessionRoots() if err != nil { - return "" + log.Warnf("codex session roots: %v", err) + return nil + } + dirs := make([]string, len(roots)) + for i, root := range roots { + dirs[i] = filepath.Join(root, now.Format("2006/01/02")) + } + return dirs +} + +func watchCodexDayDirs(watcher *transcriptWatcher, now time.Time) { + for _, dir := range codexDayDirs(now) { + watcher.watchDir(dir, "codex") } - return filepath.Join(home, ".codex", "sessions", now.Format("2006/01/02")) } func processStartOrNow(proc Process) time.Time { From f272b0622366f09875428083304e523440871865 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Thu, 22 Oct 2026 22:56:01 +0300 Subject: [PATCH 16/77] docs(docs): document prompt CLI, portable access and reference sections Bring the docs site in line with the current prompt runtime and CLI. - Add a Prompt CLI page covering discovery, authoring, render/run/observe, and help and color behavior. - Document portable permissions.access (read-only/full), how it compiles per runtime, and the codex execpolicy handling. - Replace runtimeProfile with presets and --preset, and add the Lint built-in preset. - Update approvals for the broker's OnRunState hook and Deadline, and the read-only escalation rules. - Add reference pages for Sandboxes, Configuration, Serve, Sessions, and Fixtures, and move them out of the placeholder section. - Rewrite the Gavel TODO docs around the PostgreSQL-backed lifecycle, durable plans, and fixture verification. - Correct the prompt API path to /api/v1/prompt and the prompt schema examples to typed variables and model/mode fields. BREAKING CHANGE: runtimeProfile and --runtime-profile are deprecated and ignored; use presets in frontmatter or --preset instead. --- docs/src/components/PromptApiShapes.tsx | 4 +- docs/src/components/PromptPipeline.tsx | 4 +- docs/src/data/navigation.ts | 22 +++- docs/src/pages/agents/approvals.mdx | 18 ++-- docs/src/pages/agents/embedding.mdx | 17 +++- docs/src/pages/agents/index.mdx | 2 +- docs/src/pages/agents/verification.mdx | 10 +- docs/src/pages/configuration/index.mdx | 65 +++++++++++- docs/src/pages/fixtures/index.mdx | 56 ++++++++++- docs/src/pages/index.mdx | 23 +++-- docs/src/pages/prompts/cli.mdx | 83 +++++++++++++++ docs/src/pages/prompts/format.mdx | 21 ++-- docs/src/pages/prompts/index.mdx | 1 + docs/src/pages/prompts/runtime.mdx | 84 +++++++++++----- docs/src/pages/prompts/sources-api.mdx | 12 +-- docs/src/pages/sandboxes/index.mdx | 78 +++++++++++++++ docs/src/pages/serve/index.mdx | 54 +++++++++- docs/src/pages/sessions/index.mdx | 32 +++++- docs/src/pages/todos/execution.mdx | 111 ++++++-------------- docs/src/pages/todos/format.mdx | 128 +++++------------------- docs/src/pages/todos/index.mdx | 79 ++++++--------- 21 files changed, 592 insertions(+), 312 deletions(-) create mode 100644 docs/src/pages/prompts/cli.mdx create mode 100644 docs/src/pages/sandboxes/index.mdx diff --git a/docs/src/components/PromptApiShapes.tsx b/docs/src/components/PromptApiShapes.tsx index 904deaa0..9fbb57ca 100644 --- a/docs/src/components/PromptApiShapes.tsx +++ b/docs/src/components/PromptApiShapes.tsx @@ -60,6 +60,8 @@ const renderResult = { system: "You are a commit message generator. Analyze the diff below and produce a Conventional Commit message.", validationError: "", input: { + model: "claude-sonnet-4-6", + mode: "agent", prompt: { source: "commit.prompt", user: "DIFF INPUT:\\n\\n...\\n\\nREQUIREMENTS:\\n- type: one of feat|fix|perf|refactor|test|docs|build|ci|chore|revert\\n...", @@ -80,7 +82,7 @@ export default function PromptApiShapes() {
- /api/v1/prompts + /api/v1/prompt
@@ -37,6 +41,8 @@ type Input struct { ## Timeout rule +Call `promptrun.Preflight(input)` before dispatch to check the same resolved request that `Run` will admit. It validates declarations, attachments, deadlines, model selection, runtime policies, judge prompt files, verifier registration and commit ownership without constructing a provider or running setup. Log its returned warnings separately from fatal errors. `Run` applies configured prompt-context hooks before admission and repeats its admission checks before execution. + -- **`commands`** (`[]string`) — shell commands run as pass/fail checks (exit 0 = pass); their output tail becomes the re-run feedback. This is the only part of `verify` captain itself executes, via `agent/verify.CmdVerifier`. +- **`commands`** (`[]string`) — shell commands run as pass/fail checks (exit 0 = pass); their output tail becomes the re-run feedback, via `agent/verify.CmdVerifier`. Captain also executes LLM judges; fixture evaluation belongs to the registered runner. - **`fixture`** (`string`) — a clicky-FixtureEditor markdown document (acceptance criteria / LLM-judge checklist). Captain does not implement a fixture engine; it dispatches this document to whatever claimed the `fixture` kind. - **`prompts`** (`[]string`) — `.prompt` template paths run as LLM-judge checks. Each renders against the run's context and must yield `{ok, reason, feedback}` (`agent/verify.LLMJudgeVerifier`). A judge prompt **cannot** declare its own `sandbox` or a `model` different from the run's provider — both are hard validation errors, not a silent downgrade. - **`scope`** (`""` \| `all` \| `changed`) — narrows verification to the agent's changed files instead of the whole tree. @@ -96,7 +96,7 @@ The contract fails loudly rather than guessing a verdict: | Runner behavior | Result | | --- | --- | -| Exits 0 with exactly one `report` line | The verdict. A failing fixture is still a verdict (the runner exits non-zero for it and the report says `passed: false`). | +| Exactly one valid `report` line, with exit 0 or nonzero | The report's verdict; a failed fixture can exit nonzero and still supply `passed: false`. | | Non-zero exit with no `report` line | Error: `"...exited N with no report line"`, plus the process error (e.g. a missing binary) and the stderr tail. | | More than one `report` line | Error: `"emitted more than one report line"`. | | Malformed JSON on a line | Error naming the malformed line (truncated to 200 bytes). | @@ -140,7 +140,7 @@ A running check can report where it has got to before it has a verdict, at up to `captain verify` runs a workflow's checks against a working tree without spending a generation on it — the same checks the loop votes with, driven out of the generate→verify loop: diff --git a/docs/src/pages/configuration/index.mdx b/docs/src/pages/configuration/index.mdx index 13ec22d4..9d6f10ef 100644 --- a/docs/src/pages/configuration/index.mdx +++ b/docs/src/pages/configuration/index.mdx @@ -1,11 +1,70 @@ --- layout: ../../layouts/DocsLayout.astro title: Configuration -description: Placeholder for Captain configuration documentation. -section: Next Sections +description: Saved runtime defaults, credentials, prompt sources, and verification configuration. +section: Reference --- # Configuration -This section is scaffolded for `captain configure`, `~/.captain.yaml`, provider defaults, prompt directories, memory toggles, and safety defaults. +Captain reads saved defaults from `~/.captain.yaml`. Run `captain configure` for the interactive wizard, or select a provider to save its runtime defaults or credentials. Explicit request values take precedence over saved defaults. + +## Configure a runtime + +```sh +captain configure +captain configure openai --mode agent --model gpt-6.1-sol --effort high --active +captain configure anthropic --mode agent --model sonnet --effort default +captain whoami --models=false +``` + +`--active` selects the provider used by flagless runs. `--effort default` clears the explicit effort so the model's catalog default can apply. A runtime is a model and a mechanism (`api`, `agent`, `cli`, `cmux`); the provider family is derived from the model. Each fallback uses defaults for its own provider. `--backend` and `configure --agent` have been replaced by `--mode`. + +```yaml +# ~/.captain.yaml +ai: + defaultProvider: openai + providers: + openai: + mode: agent + model: gpt-6.1-sol + reasoningEffort: high + timeout: 20m +prompts: + dirs: [~/prompts] +runtime: + presetDirs: [~/captain-presets] +chat: + presets: [Plan] +verify: + fixtureRunner: [gavel, fixtures, run, --format, captain-verify-report] +``` + +The `ai` block also supports `budgetUSD`, `maxTokens`, `temperature`, `noCache`, `noMCP`, `noHooks`, `noSkills`, `noUser`, `noProject` and `noMemory`. Defaults fill missing fields after authored layers have been composed; intentional zero or false values remain explicit. See [Runtime overlay](/prompts/runtime/) for layer order, restrictive budgets and provenance. + +## Provider credentials + +```sh +captain configure openai +captain configure openai --test +captain configure anthropic +``` + +With no runtime-default flags, selecting an API provider opens a secure token prompt. Captain validates the token against that provider before saving it in `~/.config/captain/vault`; `--test` validates without writing. Explicit runtime keys take precedence over the vault, then environment variables. Local agent runtimes use their CLI's own login. The `/whoami` page exposes token validation and runtime defaults without displaying stored tokens. + +## Sources and presets + +Prompt sources include embedded examples, built-in review prompts, configured directories, server `--prompt-dir` directories, project `.captain/prompts`, and the user config prompt directory. Local names shadow embedded names; conflicting local names require an explicit path or ID. See [Sources and API](/prompts/sources-api/) for discovery and write destinations. + +Select runtime presets in frontmatter with `presets: [Plan]`, with repeated `--preset` flags, or through the runtime editor. `--no-presets` clears the selection. `runtimeProfile` and `--runtime-profile` are deprecated and ignored. Built-in presets can be overridden by a local preset of the same name; see [Built-in runtime presets](/prompts/runtime/#built-in-runtime-presets). + +## Database contexts + +`captain serve` keeps sessions, prompt runs, approvals and catalogs in PostgreSQL. `--db-url URL` chooses the default database; repeated `--db-url name=URL` entries declare additional read-only contexts. `--context name` chooses the read context. Check the server's startup database identity before inspecting a different context. + +## Output and diagnostics + +`--json`, `--yaml`, `--markdown`, or `--format` select command result formats. `captain prompt --help` and child help use color on a human terminal, plain output with `--no-color`, `NO_COLOR`, or redirection, and Markdown in detected agent sessions. These help rules are independent of the result format. + +Increase verbosity with `-v` for HTTP access lines, `-vv` for headers/query, `-vvv` for request bodies, and `-vvvv` for response bodies. Credentials are redacted. `-Phttp.har=.tmp/captain.har` records a HAR archive; `-Phttp.har.level=metadata` excludes bodies. Root `captain --help` describes the inherited HTTP and logging properties. diff --git a/docs/src/pages/fixtures/index.mdx b/docs/src/pages/fixtures/index.mdx index 1eee98a1..041c0533 100644 --- a/docs/src/pages/fixtures/index.mdx +++ b/docs/src/pages/fixtures/index.mdx @@ -1,11 +1,61 @@ --- layout: ../../layouts/DocsLayout.astro title: Fixtures -description: Placeholder for Captain fixture documentation. -section: Next Sections +description: Claude configuration benchmarks, runtime observations, and verification fixtures. +section: Reference --- # Fixtures -This section is scaffolded for AI fixture benchmarks, repeat runs, artifact capture, direct-vs-MCP comparisons, and evidence reports. +Captain provides two measurement surfaces: `ai fixture` compares Claude CLI configurations, while `prompt observe` captures one runtime as a structured observation. Workflow verification fixtures are executed by a registered runner, described under [Verification](/agents/verification/). + +## Claude configuration benchmarks + +`captain ai fixture` reads a YAML fixture, layers `defaults` beneath each run, executes repeated trials, and reports duration, cost, tokens and tool calls. It invokes the Claude CLI and requires its login and any tools declared by the fixture. + +```sh +captain ai fixture --file examples/ai-fixtures/mission-control-investigate.yaml +captain ai fixture --file benchmark.yaml --repeat 3 --report .tmp/benchmark.md +captain ai fixture --file benchmark.yaml --report .tmp/benchmark.html --format html +``` + +```yaml +name: repository-summary +description: Compare tool exposure for the same repository question +prompt: Describe this repository's main packages. Do not change files. +repeat: 2 +defaults: + model: sonnet + timeout: 2m + permissionMode: default + disallowedTools: [Edit, Write, Bash, Agent, Task] +runs: + - name: read-and-search + tools: [Read, Glob, Grep] + - name: read-only + tools: [Read] +``` + +`runs` must contain at least one entry. Per-run fields include `prompt`, `system`, `model`, `cwd`, `timeout`, `permissionMode`, `appendSystemPrompt`, `settings`, `maxBudgetUSD`, `repeat`, `tools`, `allowedTools`, `disallowedTools`, `mcpConfig`, `addDir`, `betas`, `extraArgs`, `env`, `promptCaching`, `noSessionPersistence` and `bare`. List overrides replace the default list. `--repeat` overrides the fixture-wide repeat count; a per-run repeat still wins. + +Stream artifacts default to `/.captain/fixtures/`; use `--artifacts` to choose a destination. `--report` writes an evidence report in `markdown`, `html`, or `ansi` format. `baseline` names the comparison run for aggregate reporting. + +MCP servers are opt-in per run through `mcpConfig`; the runner uses strict MCP configuration so ambient servers do not leak into a comparison. With `allowedTools` and `bypassPermissions`, it changes the effective permission mode to `default` so non-interactive unlisted tools are denied. Other explicit permission modes are preserved. Repeated trials report aggregate duration/cost and variation; retain the per-trial streams as evidence for comparisons. + +## External tool traffic + +`captureKubernetesProxy: true` routes kubeconfig-aware Kubernetes requests through a local capture proxy. `kubeconfig` selects the source configuration. `mcpProxy: {capture: true}` wraps HTTP MCP servers from each run's `mcpConfig`; optional `headers` are merged into forwarded requests. Reports and per-run logs separate tool invocations from observed network requests. + +These proxies capture real traffic; they do not turn a mutating tool into a read-only one. Choose the target and tool policy before running a benchmark. + +## One runtime observation + +```sh +captain prompt observe --runtime agent:sonnet -p 'Explain this repository' > .tmp/observation.json +captain prompt observe review.prompt --runtime api:gpt-6.1-sol -V target=pkg/cli +``` + +`observe` is CLI-only and emits one `captain.observation/v1` JSON document. `--runtime` is required and cannot be combined with `--model` or `--mode`. Fallback chains, parallel matrices and workflow-backed prompts are rejected. `--mcp-config` and `--capture-kubernetes` request external capture; availability and capture coverage are recorded explicitly rather than treating missing measurements as zero. + +Use `captain prompt observe --help` for all source, capture and timeout flags. Observation execution can call a model and use the declared tools, just like a normal prompt run. diff --git a/docs/src/pages/index.mdx b/docs/src/pages/index.mdx index 892ee81b..b604d1dd 100644 --- a/docs/src/pages/index.mdx +++ b/docs/src/pages/index.mdx @@ -7,7 +7,15 @@ section: Start # Captain documentation -This site is the documentation home for Captain. Authored sections cover the prompts engine — how `.prompt` files are loaded, rendered, merged into `api.Spec`, and executed from the CLI and web UI — and todo execution, where gavel drives Captain's agent runtime to implement, check, and verify TODOs. +Captain runs prompts across API and local agent runtimes, records sessions, brokers approvals, and verifies generated work. Start with configuration, preview a prompt, then execute it through the CLI or workbench. Gavel embeds the same runtime for its TODO lifecycle. + +```sh +captain configure +captain prompt list +captain prompt render proposal-review -V files=proposal.md --json +captain prompt run proposal-review -V files=proposal.md +captain serve --open +``` -## Current focus +## Reference -The prompts section is grounded in the implementation under `pkg/ai/prompt`, `pkg/cli/ai_prompt_file.go`, and `pkg/cli/prompt_entity.go`. The docs intentionally describe the existing runtime behavior instead of creating a second prompt workbench. +- [Prompt CLI](/prompts/cli/) covers every prompt subcommand, terminal color, agent Markdown help and schemas. +- [Configuration](/configuration/) covers saved runtime defaults, credentials, sources and database contexts. +- [Fixtures](/fixtures/) covers benchmarks, structured observations and external verification runners. +- [Sandboxes](/sandboxes/) covers isolation, agent images, deployment and credential publishing. diff --git a/docs/src/pages/prompts/cli.mdx b/docs/src/pages/prompts/cli.mdx new file mode 100644 index 00000000..6b022c1d --- /dev/null +++ b/docs/src/pages/prompts/cli.mdx @@ -0,0 +1,83 @@ +--- +layout: ../../layouts/DocsLayout.astro +title: Prompt CLI +description: Discover, inspect, author, render, run and observe prompts, with terminal and agent help. +section: Prompts +--- + +# Prompt CLI + +`captain prompt` is the primary prompt command. Its children share the same source catalog and runtime schema. `captain ai prompt` is an alias for `captain prompt run`. + +| Command | Result | +| --- | --- | +| `captain prompt list` | Discover prompts; filter with `--query` and `--source` | +| `captain prompt get SOURCE` | Read content, metadata, schemas and version | +| `captain prompt create key=value ...` | Validate and create a writable local prompt | +| `captain prompt update SOURCE key=value ...` | Validate and replace local content | +| `captain prompt delete SOURCE` | Delete a local file; built-ins remain read-only | +| `captain prompt render [SOURCE]` | Preview messages, spec, schemas, provenance and validation | +| `captain prompt run [SOURCE]` | Render, validate and execute | +| `captain prompt observe [SOURCE]` | Execute one `--runtime` and emit observation JSON | + +`SOURCE` can be an opaque catalog ID, a bare name, a `.prompt` path, or `-` for stdin on render/run. An existing file in the current directory wins over catalog discovery. Local sources shadow embedded names; ambiguous local names need an explicit path or ID. + +## Preview before running + +```sh +captain prompt list --query review +captain prompt get proposal-review --json +captain prompt render review.prompt -V target=pkg/cli --json +captain prompt run review.prompt -V target=pkg/cli --access read-only +``` + +`render` calls no model and runs no setup. Its JSON includes the full `input` request, `resolution` and `validationError`; inspect that error before executing. For declaration-only validation, use `captain lint promptfile review.prompt`. + +## Inline text, variables and stdin + +```sh +captain prompt run --model agent:sonnet -p 'Explain this repository' +captain prompt render --model agent:sonnet -p 'Explain {{topic}}' -V topic=permissions +git diff | captain prompt run review.prompt -V patch=- +captain prompt render review.prompt --vars @inputs.json --json +``` + +Choose one positional source or `-p`; with neither, Captain reads stdin. `.prompt` files are templates. Inline and piped text are literal data unless supplied variables or `{{input}}` opt into templating. Piped input binds to `input`, or to a named variable with `-V key=-`; unused piped input is appended to the body. `-V key=@file` reads one variable from a file. `-p`, `-s`, `--append-system` and `--vars` also accept `@file` or `@url`. + +## Runtime and output + +```sh +captain prompt run review.prompt --preset Plan +captain prompt render review.prompt --no-presets --json +captain prompt run review.prompt -M agent:sonnet -M agent:gpt-6.1-sol +captain prompt run review.prompt --no-stream --json +captain prompt observe --runtime agent:sonnet -p 'Explain this repository' +``` + +Compact selectors use `mode:model:effort`, such as `agent:sonnet:high`. Repeated `-M` values replace a prompt's declared runtime matrix. `--preset` replaces its preset selection; `--no-presets` clears it. Use `--attach` for local paths or URLs and `--timeout` to supply a caller deadline; a declared `budget.timeout` takes precedence. `--json` returns structured results and `--no-stream` buffers the final result. See [Runtime overlay](/prompts/runtime/) for permissions, budgets, fallbacks and layer order. + +A foreground, single-runtime Claude Agent or Codex app-server run can ask through the terminal when stdin and stderr are terminals. Piping input removes that answer channel; redirecting stdout preserves it. See [Approvals](/agents/approvals/#foreground-terminal-runs). + +## Create and update + +```sh +captain prompt create name=hello 'content=Hello {{name}}' +captain prompt get .captain/prompts/hello.prompt --json +captain prompt update .captain/prompts/hello.prompt 'content=Hello {{name}}!' baseVersion=VERSION_FROM_GET +``` + +Creation uses the first writable source by default. Supply `target=SOURCE_ID` and `relPath=hello.prompt` to choose a destination. The generated schema endpoint lists writable sources, including empty directories. Updates can send the version returned by `get` as `baseVersion`; stale versions fail instead of overwriting another edit. Embedded content must be copied to a writable source. Both create and update validate content before an atomic write. See [Sources and API](/prompts/sources-api/#saving). + +## Help, color and schemas + +```sh +captain prompt --help +captain prompt run --help +captain prompt observe --help +captain prompt render --no-color --help +captain prompt --schema +``` + +Root help covers promptfile authoring; each child's help adds examples and its generated flags, including inherited output options. Human terminal help uses colored headings and syntax-highlighted examples. `--no-color`, `NO_COLOR`, and redirected output disable ANSI color. Detected Captain, Claude, Codex and Gemini sessions receive Markdown help without ANSI escapes. Result-format flags such as `--json` select command results rather than the help renderer. + +`--schema` exposes generated input/output schemas, enum values, runtime catalogs and provider-specific `cliArgs`. For server clients, `GET /api/captain/ai/prompt/schema` is the authoring schema and availability catalog. diff --git a/docs/src/pages/prompts/format.mdx b/docs/src/pages/prompts/format.mdx index ffdcd441..27a53e44 100644 --- a/docs/src/pages/prompts/format.mdx +++ b/docs/src/pages/prompts/format.mdx @@ -53,9 +53,9 @@ A `.prompt` file has YAML frontmatter followed by a Handlebars body. dotprompt o Declares the default parallel runtime matrix without becoming part of the request sent to each model. - runtimeProfile + presets Captain runtime catalog - Pins the runtime profile (id or name) whose presets and spec are layered beneath this frontmatter. A request runtimeProfile or --runtime-profile overrides the pin. + Selects reusable runtime presets by id or name. Request presets or repeated --preset flags replace the selection; --no-presets clears it. @@ -93,9 +93,8 @@ permissions: presets: - edit tools: - allow: - - Read - - Edit + Read: allow + Edit: allow mcp: disabled: true memory: @@ -111,14 +110,16 @@ Refactor: {{target}} `} /> -## Runtime profile pin +## Runtime preset selection -`runtimeProfile` names a saved runtime profile by id or name. Rendering resolves the profile's presets (ordered by scope), then its spec, then this frontmatter, then the caller's request or CLI flags, so the file can defer model, budget, and permission defaults to a shared profile while still overriding any of them inline. A caller that passes `runtimeProfile` on the render request or `--runtime-profile` on the command line replaces the pin; a pin that names no profile in the catalog fails the render rather than silently running without it. The render result's `resolution.trace` lists every layer that contributed. Captain binaries older than this key reject a file that uses it. +`presets` selects reusable runtime spec layers. Captain combines the selected presets, rendered frontmatter, and caller request, sorting by explicit `order`, then scope, then selection order. Ordinary presets supply defaults beneath the prompt; a higher `order` can enforce fields afterward. Saved configuration fills remaining gaps. Missing or ambiguous references fail rendering. The render result's `resolution.trace` and `resolution.provenance` explain the effective fields. See [Runtime overlay](/prompts/runtime/#precedence). - ## Precedence -
-

1. Prompt frontmatter

-

The `.prompt` file declares the base model, budget, permissions, memory, setup, and prompt metadata.

-
-
-

2. Saved defaults

-

`captain configure` values fill gaps such as default model, mode, max tokens, budget, no-cache, and memory toggles.

-
-
-

3. CLI or UI overlay

-

Explicit runtime choices override the base file and defaults. Negative toggles such as no-MCP and no-hooks stay enabled once set by any layer.

-
-
-

4. Context normalization

-

The prompt command resolves an empty workspace directory to the invocation cwd and resolves relative directories from that same cwd before provider dispatch.

-
+1. **Select presets.** Explicit request `presets` or repeated `--preset` flags replace frontmatter `presets`; `--no-presets` supplies an explicit empty selection. +2. **Compose authored layers.** Sort by ascending `order`, then scope (`global`, `context`, `surface`, `user`), preserving selection order for ties. At ordinary order, presets precede the prompt and explicit request. Restrictive catalogs intersect and the strictest nonzero budget limit wins. A high-order preset can override an ordinary request: built-in `Lint` uses `order: 100` to enforce its output schema. +3. **Fill saved defaults.** `captain configure` values supply missing model, mode, effort, generation, budget and memory settings. Each fallback inherits defaults from its own provider. +4. **Normalize and validate.** Relative or empty `setup.cwd` resolves against the invocation directory. Resolve model aliases and fallbacks and check runtime capabilities before dispatch. + +Explicit `false`, zero, empty collections and null values retain their authored presence; lower-layer toggles are not permanently latched on. Every authored layer is structurally validated even if another layer would overwrite it. `resolution.trace`, `resolution.provenance` and `resolution.warnings` describe the result. Rendering previews this resolution without running setup or calling a model. ## Runtime payload +## Portable access + +Each runtime speaks its own permission dialect: claude restricts per tool, codex restricts through its sandbox and approval policy, and gemini through an approval mode. A `permissions.tools` deny list therefore cannot make a run read-only on codex, where the shell is also how the agent reads files. `permissions.access` states the intent once, and Captain compiles it into each runtime's own dialect when the provider for that runtime is built. A fallback in another family is compiled for its own runtime too. + + + +With `read-only`, the agent may read the workspace. It cannot create, modify or delete files, spawn sub-agents, message or trigger other sessions, schedule prompts, create worktrees, use third-party MCP servers, or obtain write access by approval. Web tools and the network keep whatever `tools` and the sandbox say. `full` adds nothing; it overrides a read-only intent inherited from an earlier layer, or set with `--access full`. + +| Runtime | `read-only` compiles to | Support | +|---|---|---| +| claude agent, cli, cmux | `--disallowedTools` for every edit, write and shell tool plus every tool that acts outside the agent's own process (`Agent`, `Task`, `Workflow`, `TeamCreate`, `TeamDelete`, `SendMessage`, `RemoteTrigger`, `CronCreate`, `CronDelete`, `EnterWorktree`, `ExitWorktree`); MCP disabled. An authored sandbox is left as it is. | exact | +| codex agent, cli, cmux | native sandbox `read-only`, approval `never`, MCP disabled, and no execpolicy allow rules (see below). The shell stays, because it is codex's read path, and the sandbox confines it. | exact | +| gemini cli | `--approval-mode plan` | approximate: the gemini client enforces it, not an OS sandbox | +| api modes | nothing to restrict: no built-in file tools run | exact | + +Codex execpolicy rules need special handling. A `prefix_rule(..., decision="allow")` in `~/.codex/rules/*.rules`, or in a project's `.codex/rules`, runs the matching command outside the sandbox, even when the sandbox is read-only and approval is `never`. A rule allowing `git add` would let a read-only run write the git index. A read-only run keeps them out: + +- `codex exec` (the cli mode) runs with `--ignore-rules`. +- The app-server (the agent mode) and the interactive TUI (cmux) have no such switch. They start in a captain-managed `CODEX_HOME` at `~/.config/captain/codex-read-only` (under `$XDG_CONFIG_HOME` when set). That home links only `auth.json`, `config.toml` and `AGENTS.md` from your codex home, and it has no `rules` directory. `config.toml` has no field that declares rules. Captain's session history scans this home's `sessions` directory too. +- On those two runtimes, a project rules file that allows a command is refused before the run, with its path. Codex reads project rules from the working directory up to the nearest `.git`, and the isolated home cannot hide them. + +`captain permissions explain` shows which of these applies on each runtime. + +The contract does not cover Captain's own caller tools, which stay governed by `toolPolicy`. A posture a runtime cannot reach is refused before the model is called: on codex, `access: read-only` with `sandbox: off`, a docker or git-agent sandbox, `filesystem.access: workspace-write`, `writableRoots`, or cmux `cliArgs` looser than `sandbox: read-only` with `askForApproval: never` are all refused. The `access` rows of `captain permissions matrix` show the same table. + +### Existing tool and sandbox rules + +Captain also reads read-only intent from each runtime's own dialect, layer by layer, and the later layer wins: + +- A layer whose `permissions.tools` deny every edit, write and shell tool, such as the built-in Read-only preset, says read-only in claude's dialect. +- A layer with a native sandbox whose `filesystem.access` is `read-only` says it in codex's dialect. +- A later layer that allows an edit, write or shell tool, sets the sandbox to `off` or `workspace-write`, or sets `access: full` lifts the intent. `mode: plan` never converts, because plan mode writes its plan file. + +A converted intent is applied only on runtimes that speak another dialect, so a spec running on its own family is unchanged. On codex, the edit, write and shell denies of the built-in Read-only preset are now accepted as a read-only sandbox that never asks. Its web denies stay as they are: `web_fetch` has no codex tool and is reported as ignored, and `web_search` is still refused until codex can deny it natively, so the preset as a whole is still refused on codex. A read-only sandbox on claude also gains Edit and Write denies, because claude's sandbox confines only Bash. That is the one behaviour change, and it only tightens. + +The built-in presets themselves are unchanged. To see what a prompt becomes on each runtime, or to rewrite a block into the portable form, use: + + + +`convert` only rewrites a block when the portable form is equivalent or tighter on every runtime, and keeps any rule it did not absorb, such as a web deny, beside `access`. Otherwise it refuses and gives the reason. + ## Model and mode A runtime is the pair `(model, mode)`: the mode is the mechanism — `api`, `agent`, `cli`, or `cmux` — and the provider family is derived from the model name, never authored. The prompt workbench keeps runtime selection catalog-backed: the UI groups by provider family first, then mode, then the model list filtered to that runtime. Prompt files can name `model` and `mode` directly when the runtime should be pinned. diff --git a/docs/src/pages/prompts/sources-api.mdx b/docs/src/pages/prompts/sources-api.mdx index 19a1fa88..24f0a04b 100644 --- a/docs/src/pages/prompts/sources-api.mdx +++ b/docs/src/pages/prompts/sources-api.mdx @@ -44,7 +44,8 @@ CLI prompt commands accept an opaque prompt ID, an explicit file path, or a bare "writable": false, "model": "claude-sonnet-4-6", "variables": [ - { "name": "diff", "type": "string" } + { "name": "patch", "type": "string", "required": true }, + { "name": "maxBodyLines", "type": "integer", "required": true } ] } `} /> @@ -84,13 +85,12 @@ Rendering accepts template variables and an optional runtime `spec` overlay. It +`--dirty` carries uncommitted and ignored content into a new worktree. It does not mean discarding existing changes or running directly over a dirty source tree. `--reuse-branch` continues the branch left by one TODO's previous run; `--resume` continues its prior agent session. `--commit=false` disables lifecycle-step commits when intentionally requested. ## Plan review -`--mode plan` runs the agent read-only; the plan file path is recorded on the TODO and the status becomes `review`. From there: +```sh +gavel todos plan approve TODO_ID +gavel todos plan approve TODO_ID --run +gavel todos plan reject TODO_ID +gavel todos plan revise TODO_ID --feedback 'Separate schema and data migration' +gavel todos plan recover TODO_ID +``` - +Approve selects the reviewed revision for implementation; `--run` chains execution. Reject preserves history and removes the active selection. Revise runs an agent with feedback and returns the updated plan for review. Recover backfills the plan from the latest terminal plan-step run; use `gavel todos edit --plan` to supply one directly. -## Checking and verifying +## Definition of done -Two distinct gates: +```sh +gavel todos criteria TODO_ID +gavel todos check TODO_ID +gavel todos check TODO_ID --timeout 10m +``` -- **`gavel todos check [files...]`** — deterministic: runs each TODO's `Verification` fixtures (`--timeout` default 2m) and exits non-zero if any fail. Useful in CI. -- **`gavel todos verify [ids...]`** — agentic: Captain's verify engine reviews the TODO's commits against its `Acceptance Criteria` checklist and scores them. `--threshold` (default 80) sets the promote-to-`verified` score; `--strict` exits non-zero when any TODO fails verification. +The persisted Gavel fixture is the verification authority. It runs checks, produces test results, and evaluates its CEL verdict. An AI acceptance review, when configured, is part of that fixture rather than a separate `todos verify` command. A failed fixture supplies feedback to the execution loop; it cannot be replaced by a successful prose summary. - +Gavel owns post-verification commits, including staging, gates and session/issue trailers. Captain receives host commit hooks with `CallerOwnsCommits` so its workflow does not create an additional commit. Use `gavel todos get TODO_ID` for persisted plan, run and verification history. diff --git a/docs/src/pages/todos/format.mdx b/docs/src/pages/todos/format.mdx index 7d80381c..367e5923 100644 --- a/docs/src/pages/todos/format.mdx +++ b/docs/src/pages/todos/format.mdx @@ -1,125 +1,45 @@ --- layout: ../../layouts/DocsLayout.astro title: Todo Format -description: TODO providers, file schema, statuses, and creation paths. +description: PostgreSQL TODO content, durable plans, fixture definitions of done and portable Markdown. section: Todos --- -import CodeExample from "../../components/CodeExample.tsx"; - # Todo format -A TODO is a unit of work with a priority, a status, free-form implementation instructions, and executable definition-of-done tests. TODOs are persisted by one of two providers, selected with the persistent `--provider` flag on every `gavel todos` subcommand. - -## Providers - -
-
-

grite (default)

-

TODOs are issues in the git-backed `grite` issue tracker. Gavel maps state onto namespaced labels (`status:*`, `priority:*`, `session:*`, `plan:*`, `mode:*`) plus a marked state comment for long values such as the plan path and blocking questions. `--dir` is rejected for this provider.

-
-
-

todos (files)

-

TODOs are markdown files in a `.todos/` directory at the repo root (override with `--dir`). Enable with `--provider=todos`. Each file is YAML frontmatter plus named markdown sections.

-
-
- -## File schema - - - -### Frontmatter +A TODO stores a title, body, priority, status, acceptance criteria, definition-of-done fixture and execution history. It can also carry labels, a parent, related/dependent links, PR references and a selected Captain plan revision. Resolve TODOs by short ID, full ID, title or alias. -`priority` (`high` / `medium` / `low`) is required; `status` and `language` (`go` / `typescript` / `python`) are validated. The frontmatter embeds the fixture `FrontMatter`, so fixture keys like `build`, `exec`, `cwd`, and `env` are also available. +## Create and inspect -| Field | Purpose | -| --- | --- | -| `title`, `priority`, `status` | Identity and scheduling | -| `created`, `last_run`, `attempts` | Run bookkeeping | -| `language`, `path`, `cwd`, `branch`, `working_commit` | Scope — `cwd` defaults to the git root | -| `llm` | Model, `max_tokens`, `max_cost`, `max_turns`, `session_id`, plus recorded `tokens_used` / `cost_incurred` | -| `verify` | AI verification gate: `categories` and `score_threshold` (default 80) | -| `checks` | Per-TODO override of the post-completion check loop | -| `pr` | PR linkage: `number`, `url`, `head`, `base`, `comment_id` | -| `prompt` | Prompt override for the agent run | -| `plan_path`, `plan_status`, `run_mode` | Plan-mode state and last run mode | -| `last_run_summary`, `questions` | Agent's final summary and blocking questions when status is `ask` | +```sh +gavel todos create --title 'Fix session cache expiry' --body @task.md --priority high --verification @verification.md +gavel todos get TODO_ID +gavel todos criteria TODO_ID +gavel todos comment TODO_ID 'Focused reproduction confirmed' +``` -### Body sections +`--body`, `--plan` and `--verification` accept inline text or `@path`. Relative paths resolve from `--cwd`. A top-level `# Verification` or `## Verification` section in the supplied body is extracted into the stored fixture; explicit `--verification` content comes first, then extracted fixtures. -- **`## Steps to Reproduce`** — executable fixture commands. If they already pass before the run, the TODO is marked `skipped` without invoking the agent. -- **`## Implementation`** — free-form instructions rendered into the agent prompt. -- **`## Verification`** — executable fixture commands that are the TODO's definition of done. They run as in-loop verifiers during execution; a failure drives another agent iteration in the same session. -- **`## Custom Validations`** — additional validation tests. -- **`## Acceptance Criteria`** — a `- [ ]` checklist scored by `gavel todos verify`. +The body describes the problem, scope and acceptance criteria. The fixture contains the executable definition of done, including commands, Gavel test/lint runner blocks, tables, checklists and CEL assertions as needed. `gavel todos check TODO_ID` runs that persisted fixture and produces test results and a CEL verdict. Inspect `gavel fixtures --help` for the runner's current format. -## Statuses +## Durable plans -| Status | Meaning | -| --- | --- | -| `draft` | Not ready to run | -| `pending` | Ready, not started | -| `in_progress` | Agent running | -| `review` | A plan awaits human approval (plan mode) | -| `ask` | Agent blocked on questions a human must answer | -| `verified` | Implemented and definition-of-done fixtures passed | -| `unverified` | Implemented but the definition of done was still failing when the iteration budget ran out | -| `completed` | Finished successfully with no definition-of-done verifier | -| `failed` | Execution failed | -| `skipped` | Reproduction steps already passed | +```sh +gavel todos create --title 'Repair session lookup' --body @task.md --plan @plan.md --verification @verification.md +gavel todos plan approve TODO_ID +gavel todos edit TODO_ID --plan @revised-plan.md +``` -## Where TODOs come from +Supplying `--plan` stores an immutable Captain plan revision selected on the TODO. It awaits review by default. When the supplied plan has already been approved, creation with `--status approved` records that approval and leaves the TODO pending for execution. Plan revisions and review history remain durable; reject clears the active plan selection rather than deleting history. -Most TODOs are generated from failures by other gavel commands: +## Status and relationships -/ -gavel pr fix # sync + choose + execute in one step -`} /> +`draft` and `pending` identify work before execution; `in_progress`, `review` and `ask` identify active execution, human plan review and pending questions. `verified`, `unverified`, `completed`, `failed` and `skipped` record outcomes. Lifecycle predicates determine transitions; a provider's successful response alone does not prove that the fixture passed. -PR-sourced TODOs carry the PR metadata in frontmatter and a `build` step that fetches and checks out the PR head; a re-failure appends an `## Attempt N` section, and a later passing job flips the TODO to `completed` automatically. +`--parent TODO_ID` creates a child. Children stay out of the ordinary top-level list and counts; inspect the parent with `get` or list with `--parent`. Creation inside a TODO run inherits its TODO as parent unless `--no-parent` is supplied. Links represent related work or dependencies without changing the parent hierarchy. -TODOs can also be authored directly: +## Portable Markdown - +`gavel todos import` loads portable `.todos` Markdown into native PostgreSQL issues; `gavel todos export` writes portable Markdown from the database. These commands are explicit interchange operations. Editing an exported file does not update the live TODO until it is imported. Use each command's help for destination and collision controls. -`gavel todos create` drafts acceptance criteria with AI by default (`--criteria=false` to skip). +Source TODO/FIXME comments enter the backlog through `gavel todos sync`. External issue publication is explicit through `gavel todos push` or creation with `--github`. diff --git a/docs/src/pages/todos/index.mdx b/docs/src/pages/todos/index.mdx index 4c32e632..357fb34e 100644 --- a/docs/src/pages/todos/index.mdx +++ b/docs/src/pages/todos/index.mdx @@ -1,69 +1,46 @@ --- layout: ../../layouts/DocsLayout.astro title: Todo Execution -description: How gavel drives Captain's agent runtime to execute TODOs. +description: How Gavel's PostgreSQL-backed TODO lifecycle embeds Captain. section: Todos --- -import CodeExample from "../../components/CodeExample.tsx"; - # Todo execution -Gavel's `todos` subsystem is the task-execution side of its failure-to-fix loop. Other gavel commands *create* TODOs from failing tests, lint violations, CI jobs, and PR review comments; `gavel todos` inspects, plans, executes, verifies, and commits them. The actual implementation work is done by a Claude or Codex coding agent driven **in-process through Captain's AI runtime** — gavel imports `github.com/flanksource/captain/pkg/ai` and composes an `agent.Runner`; it never shells out to a `claude` or `captain` binary in the run path. - -## How Captain and gavel relate - -The dependency is one-directional: gavel embeds Captain, Captain has no awareness of gavel. +Gavel owns TODOs, their lifecycle, acceptance criteria, fixture verification and commit finalization. Captain owns prompt rendering, runtime resolution, provider execution, approvals, session recording and the generate/verify loop. Gavel embeds Captain through Go APIs; it does not require the `captain` CLI to dispatch a run. A selected runtime may launch its own agent CLI or use its API transport. -
-
-

Gavel owns the workflow

-

TODO files, providers, discovery, grouping, statuses, prompts, retry loops, and commit finalization all live in gavel's `todos/` package and `gavel todos` CLI.

-
-
-

Captain owns the agent runtime

-

Gavel builds Captain `ai.Request`s, selects a Captain runtime — the `(model, mode)` pair, where mode is `api`, `agent`, `cli`, or `cmux` — and streams events from Captain's `agent.Runner`, the same runtime documented under AI Agents.

-
-
-

Prompts are Captain prompts

-

The run and plan instructions are dotprompt files (`todos/prompt/todos-run.prompt`, `todos-plan.prompt`) rendered through the same engine described in Prompts.

-
-
-

Verification reuses fixtures

-

A TODO's `Steps to Reproduce` and `Verification` sections are executable fixture tests, compiled into in-loop verifier plugins so a failing definition-of-done drives another agent iteration.

-
-
+TODOs are PostgreSQL-backed issues. Markdown `.todos` files are portable import/export artifacts rather than the live store; grite and file-provider selection are no longer the runtime workflow. -## Lifecycle at a glance +## Typical flow -1. **Create** — `gavel test|lint|verify|pr status --sync-todos` writes TODOs from failures, or author one with `gavel todos create`. -2. **Select** — `gavel todos run` discovers pending TODOs (filter with `--status`, pick interactively with `-i`, batch with `--group-by`). -3. **Plan (optional)** — `--mode plan` runs the agent read-only and parks the TODO in `review` until a human approves, rejects, or revises the plan. -4. **Execute** — the agent implements the change; `Verification` fixtures run in-loop until they pass or the iteration budget runs out. -5. **Commit** — gavel (not the agent) stages and commits via `gavel commit` after each TODO, unless `--commit=false`. -6. **Verify** — `gavel todos verify` scores the committed work against the TODO's acceptance criteria with an agentic review pass and promotes it to `verified` at or above the threshold. +```sh +gavel todos list +gavel todos list --all --done +gavel todos get TODO_ID +gavel todos steps TODO_ID +gavel todos run TODO_ID --step plan +gavel todos plan approve TODO_ID +gavel todos run TODO_ID +gavel todos check TODO_ID +``` -## Quick start +`run` requires explicit IDs. Without `--step`, it selects the next applicable lifecycle step; `steps` shows the available steps and where a TODO stands. Planning stores a durable Captain plan revision for human review. Implementation runs through Captain and Gavel verifies the persisted definition-of-done fixture before its post-verification commit step. - +## Further reading -## Where to go next +- [Todo Format](/todos/format/) covers content, durable plans, verification and portability. +- [Execution and Verification](/todos/execution/) covers lifecycle steps, review, runs and checks. +- [Embedding a Run](/agents/embedding/) documents Captain's execution and recording API. -- [Todo Format](/todos/format/) covers providers (grite vs `.todos/` files), frontmatter, body sections, statuses, and the `--sync-todos` creation paths. -- [Execution and Verification](/todos/execution/) covers run modes, drivers, flags, the check loop, plan review, and AI verification. +Use the installed `gavel todos --help` for the complete Gavel flag reference; Captain's documentation describes the integration boundary. From 3065cfcc6c5661fd8246f464bb05c3430a127438 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Thu, 22 Oct 2026 22:56:07 +0300 Subject: [PATCH 17/77] docs(readme): condense README around prompts and presets Shorten the root README to an overview, quick start, prompt authoring, verification, and a command map. Detailed reference material (fixtures, sandbox credentials, git-agent deployment, whoami and configure details) moves to the docs site. Update the runtimeprofiles README to the preset model. RequestedProfile, PinnedProfile, DefaultProfile, the prompt runtimeProfile field and --runtime-profile are deprecated in favor of RequestedPresets, frontmatter presets and --preset. Mark the unified approval callback plans as historical design records that point to the current approvals guide. Fix the DeepSeek attachment example to pass the prompt with -p, matching the current CLI. --- README.md | 935 ++---------------- .../unified-approval-callback-examples.md | 2 + docs/plans/unified-approval-callback.md | 2 + pkg/ai/prompt/README.md | 2 +- pkg/runtimeprofiles/README.md | 8 +- 5 files changed, 115 insertions(+), 834 deletions(-) diff --git a/README.md b/README.md index ea95867d..49a39947 100644 --- a/README.md +++ b/README.md @@ -1,877 +1,152 @@ # Captain -Captain is a Go CLI for working with **Claude Code sessions, hooks, and sandboxes**. - -It provides tools to: - -- inspect Claude Code project/session history -- summarize tool usage, paths, binaries, and API cost -- list files changed by a session -- install Claude Code hooks -- run a workflow's **verification** checks — commands, LLM judges, and fixtures — as a definition of done -- test and use AI providers from the command line -- run iterative AI agents with verifiers, worktrees, and commits -- generate/build/run containerized Claude Code sandboxes -- inspect and clean stored Claude project session data -- expose captain commands as an MCP server -- run a web UI for launching and chatting with AI agents -- configure default backend, model, and AI safety toggles - -```xml h=185px w=358px preview -
- -
$2,500
- -

Drag to adjust — the figure updates live.

- -
-``` - -```html preview -
-
- -
-``` - -## What it does - -From the codebase, Captain is organized around a few core capabilities: - -### 1. Claude Code history and cost analysis - -Captain reads Claude session history and exposes commands for: - -- `history` — inspect tool usage from Claude sessions -- `info` — show project/session metadata for the current directory -- `cost` — estimate and group token/API usage across sessions -- `projects list` — list tracked Claude projects and sessions -- `projects clean` — remove old session history - -It analyzes: - -- tools used -- files/directories read and written -- domains accessed -- binaries executed -- approval / denial state -- categories of bash activity -- token and cost summaries - -### 2. Claude hooks - -Captain can install hook commands into Claude settings for: - -- **PreToolUse bash scanning** via `hook bash-check` - -The bash-check hook scans bash commands and can deny unsafe or disallowed commands. - -### 3. Verification - -`captain verify` runs the checks an `api.Workflow` declares against a working tree and reports each one's verdict: - -- `--command` — a shell command run as a pass/fail check (repeatable) -- `--prompt` — a `.prompt` LLM judge, judged by the run's provider (repeatable) -- `--fixture` — a fixture document handed to the runner configured as `verify.fixtureRunner` in `~/.captain.yaml` - -The same checks are the generate→verify loop's definition of done: a failing verdict's output feeds the next iteration. A declared check with nothing to run it is an error, never a silent pass. - -`captain verify` is local only — it is excluded from both the REST API and the MCP tool set, because `--command` runs through `sh -c` against a caller-chosen `--cwd`, and published as REST or MCP that would be unauthenticated remote code execution. - -### 4. Session changes - -`captain changes` lists the files written or edited during a Claude Code or Codex session: - -- defaults to the most recent session in the current directory -- `--session-id` targets a specific session by exact or prefix match -- `--all` searches across all projects -- `--claude` / `--codex` filter by session source -- `--agents` (default: true) includes files edited by nested sub-agents -- `--plans` / `--ignored` control whether plan files and git-ignored files are shown - -### 5. AI provider utilities +Captain is a Go CLI and embeddable runtime for AI prompts, agent execution, verification and session history. It runs API, agent, CLI and cmux runtimes selected by model, records Claude and Codex sessions, brokers approvals, and exposes a local web workbench. -Captain includes provider-agnostic AI utilities under `captain ai`: - -- `ai prompt` — send a prompt to a selected backend/model -- `ai agent` — run an iterative agent loop with optional verifiers, a throwaway git worktree, commit, and LLM judge -- `ai models` — list model information -- `ai test` — verify provider connectivity -- `ai fixture` — run a YAML benchmark fixture across multiple Claude configurations and capture a markdown evidence report - -Supported backends are inferred from code and dependencies, including: - -- Anthropic -- Gemini / Google -- OpenAI-compatible paths via the internal provider layer -- CLI/provider abstractions for local tool-backed backends (claude, codex, gemini) - -### 6. Adapter status and configuration - -- `whoami` — lists every AI adapter (API providers and CLI agents), how each is authenticated, whether its binary is installed, and the models it exposes -- `configure` — configure per-provider agent, model, and effort defaults in `~/.captain.yaml`, or validate and save direct-provider API tokens in `~/.config/captain/vault` - -### 7. Web UI and MCP server - -- `serve` — starts an HTTP API and embedded web UI for launching AI agents and opening follow-up chat sessions; supports `--dev` to proxy to the Vite dev server -- `mcp` — exposes captain commands (history, info, cost, changes, verify, etc.) as MCP tools so Claude Code can invoke them directly - -### 8. Utility commands - -- `cmux info ` — resolves all processes in a cmux surface, pane, or workspace and reports runtime, CPU, memory, listening TCP ports, and optional Go stacks -- `cmux screenshot` — captures a screenshot of the active browser surface in cmux and copies the path to the clipboard -- `port kill ` — finds and kills the process listening on a TCP port - -### 9. Container sandbox builder - -Captain can discover Claude-related local configuration and package it into a container sandbox. - -Supported workflows include: - -- `container` — interactive TUI -- `container list` — list discovered components -- `container generate` — generate Dockerfile/build context and sandbox config -- `container build` — build the sandbox image -- `container run` — run the generated sandbox -- `sandbox presets` — list available sandbox-runtime presets - -The container workflow is designed to package things like: - -- Claude config -- agents -- commands -- hooks -- MCP server config -- project settings -- token/env passthrough -- sandbox-runtime presets for languages/tools +## Quick start -## Project layout +Build with the Go version declared in [go.mod](go.mod), Node.js/pnpm for the web assets, and [Task](https://taskfile.dev) installed: -```text -captain/ -├── cmd/captain/ # CLI entrypoint -├── docs/ # Astro documentation site -├── pkg/ai/ # AI abstraction, provider config, models -├── pkg/ai/agent/ # Iterative agent loop, plugins (verify, worktree, judge) -├── pkg/ai/fixture/ # YAML fixture runner for Claude configuration benchmarks -├── pkg/api/ # HTTP API types and handlers (used by serve) -├── pkg/bash/ # Bash scanning, classification, rules -├── pkg/captainconfig/ # ~/.captain.yaml config load/save -├── pkg/claude/ # Claude history, sessions, parsing, formatting -├── pkg/cli/ # Cobra/clicky command implementations -├── pkg/cli/webapp/ # Embedded React web UI (served by captain serve) -├── pkg/cmux/ # Terminal multiplexer integration (processes and screenshots) -├── pkg/collections/ # Generic collection utilities -├── pkg/container/ # Sandbox discovery, generation, build/run logic -├── pkg/container/base/ # Embedded agent base image (Dockerfile, deps.yaml, entrypoint.sh) -├── pkg/git/ # Git worktree helpers -├── pkg/sandbox/ # Token/preset/sandbox helpers -├── Makefile # Thin wrapper around Taskfile -└── Taskfile.yaml # Main developer tasks +```sh +task www:build +make build +.bin/captain configure +.bin/captain prompt list +.bin/captain prompt run --model agent:sonnet -p 'Explain this repository' +.bin/captain serve --open ``` -## CLI overview - -Top-level commands exposed by `cmd/captain/main.go`: - -```bash -captain history -captain info -captain cost -captain changes -captain sandbox -captain ai -captain whoami -captain configure -captain serve -captain verify -captain hook -captain projects -captain container -captain mcp -captain cmux -captain port -``` +Local agent runtimes require their CLI and its login. API runtimes require provider credentials; `captain configure openai` securely validates and stores an API token. `captain whoami --models=false` inspects runtime readiness. Server/session persistence uses PostgreSQL; startup logs identify the selected database. -### History +## Prompts -```bash -captain history -captain history --summary -captain history --all -captain history --tool Bash --since now-7d -captain history --category git --compact -captain history --session-id 019e0365-dc2a-7ad0-a5a8-78936481a928 -captain history 019e0365-dc2a-7ad0-a5a8-78936481a928 -``` +Keep instructions and runtime declarations in a `.prompt` file: -Useful flags include: - -- `--file` -- `--tool` -- `--dir` -- `--category` -- `--approved` -- `--session-id` -- `--limit` -- `--since` -- `--all` -- `--short` -- `--compact` -- `--summary` - -### Info - -```bash -captain info -captain info --path /path/to/project +```yaml +--- +name: Review a package +model: agent:sonnet +permissions: + access: read-only +budget: + timeout: 10m +input: + default: + target: pkg/cli +--- +{{role "user"}} +Review {{target}} for correctness. Report findings with file paths and lines. ``` -Shows project root detection, Claude project directory, session counts, history range, and tool call totals. - -### Cost +Save as `review.prompt`, preview the effective request, then execute: -```bash -captain cost -captain cost --group-by project -captain cost --group-by model -captain cost --group-by tool -captain cost --group-by category -captain cost --session-id 019e0365-dc2a-7ad0-a5a8-78936481a928 -captain cost --all --since now-30d +```sh +captain lint promptfile review.prompt +captain prompt render review.prompt -V target=pkg/promptrun --json +captain prompt run review.prompt -V target=pkg/promptrun +captain prompt run review.prompt -M agent:sonnet -M agent:gpt-6.1-sol ``` -Supported groupings from the code: - -- `session` -- `project` -- `model` -- `day` -- `dir` -- `file` -- `tool` -- `category` - -### Changes - -```bash -captain changes -captain changes --session-id -captain changes --all --since now-7d -captain changes --claude -captain changes --agents=false +Render performs no model call or setup. Files are templates; inline `-p` and piped text are literal unless variables or `{{input}}` opt into templating. Piped input binds to `input`, a named `-V key=-`, or is appended when unused. Use `--attach` for files/URLs, `--preset` for reusable runtime layers and `--no-stream --json` for a buffered structured result. + +```sh +captain prompt --help +captain prompt run --help +captain prompt render --no-color --help +captain prompt --schema ``` -Lists the files written or edited during a Claude Code or Codex session. Defaults to the most recent session in the current directory. +`prompt` and every child command have colored terminal help, plain output with `--no-color`, `NO_COLOR` or redirection, and Markdown in detected agent sessions. Root help covers authoring; child help adds command examples and generated flags. See the [Prompt CLI guide](docs/src/pages/prompts/cli.mdx), [format](docs/src/pages/prompts/format.mdx), [runtime composition](docs/src/pages/prompts/runtime.mdx) and [sources/API](docs/src/pages/prompts/sources-api.mdx). -### Hook installation +## Command map -Install the bash safety hook: +| Area | Commands | Documentation | +| --- | --- | --- | +| Prompts | `prompt list/get/create/update/delete/render/run/observe`, `lint promptfile` | [Prompt CLI](docs/src/pages/prompts/cli.mdx) | +| Runtime configuration | `configure`, `whoami`, `runtime-preset`, `permissions explain/matrix/convert` | [Configuration](docs/src/pages/configuration/index.mdx) | +| Verification | `verify`, prompt `workflow.verify` | [Verification](docs/src/pages/agents/verification.mdx) | +| Sessions | `sessions`, `history`, `info`, `cost`, `changes`, `browser ls` | [Sessions](docs/src/pages/sessions/index.mdx) | +| Web/API | `serve`, `mcp`, `token` | [Serve](docs/src/pages/serve/index.mdx) | +| Benchmarks | `ai fixture`, `prompt observe` | [Fixtures](docs/src/pages/fixtures/index.mdx) | +| Isolation | `container`, `sandbox`, `sandbox credentials`, `sandbox git-agent` | [Sandboxes](docs/src/pages/sandboxes/index.mdx) | +| Gavel integration | `gavel todos` embeds Captain | [TODO lifecycle](docs/src/pages/todos/index.mdx) | -```bash -captain hook bash-check install -captain hook bash-check install --user -``` +`captain ai prompt` aliases `captain prompt run`. Other AI utilities include `ai agent` for explicit generate/verify workflows, `ai models`, `ai test`, `ai tokens` and `ai mock`. Use each command's help for its current flags. A runtime is `(model, mode)`; mode is `api`, `agent`, `cli` or `cmux`, with provider derived from the model. Configure provider defaults with `captain configure openai --mode agent --model gpt-6.1-sol --effort high --active`. -### Verification +## Verification and embedding -```bash -captain verify --command "go test ./..." --command "golangci-lint run" +```sh +captain verify --command 'make build' --command 'go test ./pkg/ai/prompt' captain verify --fixture acceptance.md --cwd /path/to/repo -captain verify --prompt review-diff.prompt --model claude-sonnet-4-6 ``` -Running fixtures needs a runner, since captain declares fixtures but does not execute them: +Fixtures require a runner, configured in `~/.captain.yaml`: ```yaml -# ~/.captain.yaml verify: - fixtureRunner: [gavel, fixture, verify] -``` - -The runner is handed the fixture document on stdin, plus `--cwd ` and one `--changed ` per changed file, and answers on stdout with NDJSON: any number of `{"progress": }` lines, then exactly one `{"report": }`. - -### AI utilities - -```bash -captain ai prompt --model claude-sonnet-4 --prompt "Summarize this diff" -captain ai agent --prompt "Fix the failing tests" --verify "go test ./..." -captain ai agent --prompt "Refactor this module" --worktree --commit --judge "all tests pass" -captain ai test --model gemini-2.0-flash -captain ai models -captain ai fixture --file examples/ai-fixtures/mission-control-investigate.yaml + fixtureRunner: [gavel, fixtures, run, --format, captain-verify-report] ``` -Relevant provider flags include: - -- `--model` -- `--backend` -- `--api-key` -- `--no-cache` -- `--budget` -- `--debug` - -#### AI agent - -`captain ai agent` runs an iterative AI agent loop with optional quality gates: - -- `--prompt` / `-p` — task prompt (required; can be piped from stdin) -- `--system` / `-s` — system prompt override -- `--verify` — shell command run after each turn; non-zero exit triggers a re-run (repeatable) -- `--max-iterations` — max verify-and-rerun iterations (default: 1) -- `--scope` — verifier scope: `changed` (only changed files) or `all` (default) -- `--worktree` — run in a throwaway git branch/worktree -- `--branch` — worktree branch name (default: `captain/agent-`) -- `--commit` — commit changes on the worktree branch (requires `--worktree`) -- `--judge` — LLM rubric; fails a turn when the judge rejects the result - -#### Fixture benchmarks - -`captain ai fixture` runs the same prompt against multiple Claude -configurations (different models, tool allowlists, MCP servers, prompt -caching on/off) and prints a side-by-side table of duration, cost, -tokens, and tool-call counts. It's intended to produce **evidence** that -one approach — e.g. a structured MCP — is faster and cheaper than a -Bash/CLI equivalent. - -```bash -captain ai fixture -f examples/ai-fixtures/mission-control-investigate.yaml -captain ai fixture -f examples/ai-fixtures/mission-control-describe.yaml --report /tmp/mc-describe.md -captain ai fixture -f examples/ai-fixtures/mission-control-multistep.yaml --repeat 5 -``` +The external runner receives fixture Markdown on stdin plus cwd/changed-file arguments and returns NDJSON progress followed by one report. Captain's `verify` command is local only. Workflow prompts can declare commands, LLM judges and fixtures under `workflow.verify`; failed verdicts feed the next iteration up to `maxIterations`. -Flags: - -- `--file` / `-f` — path to the YAML fixture (required) -- `--report` / `-r` — write an evidence report (headline, metrics table, per-run config, tool-usage breakdown) to this path -- `--format` — report format: `markdown` (default), `html`, or `ansi` -- `--artifacts` — directory for per-run `stream-json` captures (default: `/.captain/fixtures//`) -- `--repeat` — override every run's repeat count (useful for smoke tests: `--repeat 1`) - -YAML schema (abridged): - -```yaml -name: my-benchmark -description: What you're measuring and why -prompt: | - The prompt sent to every run (can be overridden per-run). -baseline: direct # which run to compare against for Speedup/Cheaper ratios -repeat: 3 # default N per run; overridable per-run and via --repeat - -defaults: - timeout: 3m - permissionMode: bypassPermissions - promptCaching: true - model: claude-sonnet-4 - -runs: - - name: direct - tools: [Bash] - allowedTools: ["Bash(kubectl *)", "Bash(aws *)"] - - - name: mission-control - tools: [default] - mcpConfig: [.mcp.json] - allowedTools: ["mcp__mission-control__*"] - repeat: 5 # overrides fixture-level repeat for this run -``` - -#### Isolation guarantees - -Two rules the runner enforces for you so direct-vs-MCP comparisons stay -honest — both are automatic, no extra flags needed: - -- **MCP is opt-in per run.** A run gets MCP servers only when `mcpConfig` - is set. With no `mcpConfig`, the runner passes `--strict-mcp-config` - with an empty inline config, so ambient `.mcp.json` in the fixture - directory and user-level MCP servers are never picked up. -- **`allowedTools` is treated as a real allowlist.** Claude CLI's - `--allowedTools` is natively an auto-approve list, not a restriction — - under `bypassPermissions` the model can still reach for anything. When - a run specifies `allowedTools`, the runner demotes the effective - `--permission-mode` from `bypassPermissions` to `default` so unlisted - tools are denied in non-interactive mode. If you set `permissionMode` - to anything other than `bypassPermissions` explicitly, your choice is - preserved. Runs without `allowedTools` keep whatever permission mode - they asked for. - -Practical consequence for a direct-vs-MCP fixture: the `direct` run with -`allowedTools: [Bash(kubectl *), ...]` can only shell out to those -patterns; the `mission-control` run with -`allowedTools: [mcp__mission-control__*]` can only use MCP — Bash is off -even though it's a built-in. Neither run can accidentally borrow from -the other's toolset. - -Supported per-run fields: `name`, `prompt`, `system`, `model`, `timeout`, -`cwd`, `permissionMode`, `appendSystemPrompt`, `settings`, -`maxBudgetUSD`, `repeat`, `tools`, `allowedTools`, `disallowedTools`, -`mcpConfig`, `addDir`, `betas`, `extraArgs`, `env`, `promptCaching`, -`noSessionPersistence`, `bare`. See -[`examples/ai-fixtures/`](examples/ai-fixtures/) for working benchmarks. - -Repeats (`repeat: N`) execute each run N times and report the mean -duration/cost plus a sample standard deviation — single-shot LLM numbers -are noisy and N≥3 makes comparisons defensible. The raw per-iteration -`stream-json` is saved under the artifacts directory so every claim in -the report is reproducible. - -#### Kubernetes proxy capture - -Set `captureKubernetesProxy: true` at the fixture level to route every -`kubectl` call made during the fixture through a captain-managed reverse -proxy, and record both layers of activity: - -```yaml -captureKubernetesProxy: true -kubeconfig: ~/.kube/config # optional; defaults to client-go discovery -``` - -When enabled, the runner: - -- starts a localhost reverse proxy that loads the user's kubeconfig (auth - plugins included) and forwards to the real cluster -- generates a temp kubeconfig pointing at the proxy and injects - `KUBECONFIG=` into every run's environment, so kubectl can't - bypass it -- writes a JSONL log per run/iteration to - `/-.kubectl.jsonl` with two record types: - - `{"type":"command","command":"kubectl get pods -n prod"}` — literal - CLI invocation parsed from the model's Bash tool calls - - `{"type":"request","method":"GET","path":"/api/v1/...","status":200}` - — every API call observed by the proxy -- surfaces a **Kubectl activity** section in the report with per-run CLI - and API counts plus a few sample commands - -### Container sandbox workflow - -```bash -captain container -captain container list -captain container generate -captain container generate -i -captain container build --preset golang -captain container run -captain sandbox presets -``` +Go hosts call `promptrun.Preflight` and `promptrun.Run` with a resolved spec, prepared attachments, timeout and optional recording/approval settings. Gavel uses this same seam and owns its commit finalization. See [Embedding a run](docs/src/pages/agents/embedding.mdx), [Approvals](docs/src/pages/agents/approvals.mdx), [runtime composition](pkg/runtimeprofiles/README.md), [prompt rendering](pkg/ai/prompt/README.md), [recording](pkg/promptrun/README.md), [chat](pkg/aichat/README.md) and [budget rules](pkg/budgets/README.md). -Important generate/build flags: - -- `--interactive` -- `--preset` -- `--base` -- `--mode copy|mount` - -### Whoami - -```bash -captain whoami -captain whoami --backend anthropic -captain whoami --models=false -captain whoami --no-cache -``` - -Lists every AI adapter (API providers and CLI agents: `anthropic`, `openai`, `gemini`, `claude-cli`, `claude-agent`, `codex-cli`, `gemini-cli`), their authentication method, binary availability, and a live model listing. - -Provider model listings are resolved through credential- and endpoint-scoped entries under `~/.config/captain/models/` (24h TTL), and priced from the OpenRouter snapshot in `~/Library/Caches/flanksource/openrouter-pricing.json` (24h TTL). The model cache uses a machine-local keyed namespace, so different provider accounts cannot reuse one another's availability. `--no-cache` skips both caches, re-queries every provider's model endpoint plus OpenRouter pricing, and rewrites only the affected model-cache entries with the fresh result. Add `-v` to see an access line per request, `-vv` for headers and query params, `-vvv` for request bodies, `-vvvv` for response bodies; credentials are redacted at every rung. Failed requests (status >= 400 or a transport error) are logged at the default verbosity. `-Plog.level.http=` raises HTTP logging alone, and `-Phttp.log.base-level=` (or `HTTP_LOG_BASE_LEVEL`) shifts the whole ladder. - -To keep the traffic instead of watching it scroll past, `-Phttp.har=` writes every request/response pair — including redirect hops and retries — to a HAR 1.2 archive you can open in browser DevTools. It applies to any command, not just `whoami`, and the file is written even when the command fails. `-Phttp.har.level=metadata` records headers, query strings and timings without bodies; `-Phttp.har.maxBodySize=` changes the 64 KB per-body cap (`0` for none). Credentials are masked the same way as in the wire log, which means the archive is safe to attach to a bug report but cannot be replayed — `-Phttp.har.sensitive=true` keeps them verbatim and writes the file `0600`. Use `-Phttp.captain.har=` to capture captain's own traffic when a shared `http.har` is already set. - -### Configure - -```bash -captain configure -captain configure openai -captain configure openai --test -captain configure openai --agent codex-agent --model gpt-5.6-sol --effort high --active -``` - -The providerless interactive wizard writes `~/.captain.yaml` with defaults for backend, model, reasoning effort, budget, timeout, and feature toggles (caching, MCP, hooks, skills, user/project settings, memory). - -With a provider and any of `--agent`, `--model`, `--effort`, or `--active`, `configure` saves provider-specific runtime defaults in `~/.captain.yaml`. `--effort default` clears an explicit effort so the selected model chooses its own default. The active provider supplies the agent and model for completely flagless runs. Explicit command flags still win, and each fallback model independently inherits defaults from its own provider. - -Passing `anthropic`, `openai`, `gemini`, or `deepseek` securely prompts for an API token, validates it with the provider's model-list endpoint, and saves it to `~/.config/captain/vault` only when validation succeeds. `--test` validates the currently effective token without writing. Automation may use `--token`, but interactive input is preferred because command-line arguments can be retained in shell history or process listings. Explicit runtime keys take precedence over the vault, and the vault takes precedence over environment variables. - -The `/whoami` page in `captain serve` exposes the same token operations plus agent, model, effort, and active-provider controls. Stored tokens are never displayed; only a masked identifier and credential source are returned. - -### Serve - -```bash -captain serve -captain serve --port 8080 -captain serve --dev -go run ./cmd/captain serve --dev --open -task www:dev -task www:build -``` - -Starts an HTTP API and embedded web UI. The UI launches `captain ai agent` operations and opens follow-up chat windows that resume the returned session. `--dev` keeps the Go API on the configured `--port` (`9020` by default), starts Vite on a random free port, and proxies `/api` to the API. Pass `--ui-port` to use a specific Vite port. Use `task www:dev` for the local Go-backed Vite proxy with the browser opened, and `task www:build` to rebuild the embedded web UI assets. - -### MCP server - -```bash -captain mcp -``` +## History, hooks and utilities -Exposes captain commands as MCP tools. Auto-exposes all commands except `sandbox`, `projects`, `container`, `hook`, and `ai`. - -### Browser sessions - -```bash -# List live agent-browser sessions with their cost and owning agent session -captain browser ls - -# Include sessions whose daemon has exited, and search by name/pid/agent session +```sh +captain history --summary +captain history --tool Bash --since now-7d +captain cost --group-by model +captain changes --session-id SESSION_ID +captain sessions get SESSION_ID --json --limit 0 captain browser ls --all -captain browser ls -q 8c630de6 - -# Register captain as an agent-browser launch plugin (inspect the merge first) -captain browser install --global --dry-run -captain browser install --global -``` - -``` - SESSION AGE CPU MEMORY PID AGENT SESSION PROJECT - captain-fb7c9f910548 12m 3.1% 412MB 11473 claude 8c630de6 captain - designpg/default 2h4m 0.4% 180MB 9921 codex 01f2a9c clicky-ui ``` -An `agent-browser` session is only a name plus a set of sidecar files, and its `.pid` holds the **daemon's** pid — the browser itself is an unrecorded child of that daemon. So CPU and memory are summed across the daemon's whole process tree, and age comes from the daemon's start time. - -The owning agent session is resolved from three independent signals, first hit wins, and the one used is reported as the row's link source: - -1. **`env`** — the daemon inherits the environment of the shell the agent ran `agent-browser` from, including `CLAUDE_CODE_SESSION_ID` or `CODEX_THREAD_ID`. This needs no setup and works for browsers started before the plugin was installed. -2. **`sidecar`** — the record `captain browser install` arranges for, written to `~/.captain/browser//.json` when the browser launches. Covers the cases where the environment cannot be read. -3. **`ancestor`** — the nearest claude/codex process above the daemon in the process tree. - -`captain browser install` merges captain into `agent-browser.json` as a `launch.mutate` plugin, preserving the rest of the configuration. The plugin appends nothing to the launch: agent-browser hashes the launch configuration into `.config`, and a hash that varied per agent session would restart the daemon and discard the browser's state. Captain never deletes agent-browser's sidecar files — `agent-browser doctor` owns that cleanup. - -Install also creates `~/.captain/browser` and registers it as writable in both agent sandboxes, because the plugin runs inside whatever sandbox confines the agent's own tools and cannot grant itself access once it is running: - -| Agent | File | Key | -|---|---|---| -| Claude Code | `~/.claude/settings.json` | `sandbox.filesystem.allowWrite` | -| codex | `~/.codex/config.toml` | `[sandbox_workspace_write].writable_roots` | - -Without this the plugin's write is denied as a bare "operation not permitted" and browsers silently go unattributed. `pkg/agentsandbox.EnsureWritable` is the reusable entry point for any other captain feature that has to write from inside an agent's sandbox; pass `--sandbox=false` to skip it. The codex edit is line-level so comments and ordering survive; `settings.json` is rewritten by `encoding/json` and comes back key-sorted, exactly as `captain hook monitor install` already leaves it. - -Browsers a session opened also appear on `captain sessions get ` under `browsers`. - -### Utility commands - -```bash -# Inspect every process attributed to a copied cmux surface -captain cmux info \ - surface_ref=surface:21 \ - surface_id=65BB4725-B785-48DE-B3FD-31167ECB8300 - -# Pipe the Copy IDs block directly from the clipboard -pbpaste | captain cmux info - -# Inspect a PID and request a Go goroutine stack through gops -captain cmux info 33745 --stack - -# Screenshot active browser surface in cmux -captain cmux screenshot +History filters include tool, category, path, time range and session. Changes defaults to the latest session in the current directory; `--agents=false` excludes nested agents. Token costs distinguish recorded usage, provider-reported cost and estimates; see [Sessions](docs/src/pages/sessions/index.mdx). -# Kill the process on a TCP port -captain port kill 3000 -``` - -## Build and development - -This repo uses `task` as the main task runner. - -### Build - -Build the web UI before the Go binary so the generated JavaScript and CSS assets -are included in the embedded filesystem: - -```bash -task www:build -task build -``` - -Binary output: - -```text -.bin/captain +```sh +captain hook bash-check install --user +captain hook monitor install +captain hook monitor install --capture-cost +captain browser install --global --dry-run ``` -### Docs - -```bash -task docs:dev -task docs:build -``` +The bash-check hook scans shell calls. Monitor hooks track session lifecycle; `--capture-cost` opts into Claude's custom status line and records its client-side estimate separately from provider billing. Installation refuses a higher-precedence project status line that would override it. Browser installation previews/merges an agent-browser launch plugin; see [browser attribution](docs/src/pages/sessions/index.mdx#browser-sessions). -The Astro docs site lives in `docs/`. The prompts engine is the first complete section; other Captain areas are scaffolded for future expansion. +`captain cmux info` accepts copied surface IDs, a PID or stdin and reports process trees, resource use and listening ports; `--stack` requests Go stacks through gops. `captain cmux screenshot` captures the active browser surface. `captain port kill PORT` stops the port's listener. `projects list` and `projects clean` inspect and maintain stored Claude project history. -### Test +## Development -```bash -task test -# or +```sh +make build +make lint +gavel test ./pkg/ai/prompt make test -``` - -### Lint - -```bash -task lint -``` - -### Install - -```bash task install ``` -By default this copies the built binary to: - -```text -/usr/local/bin/captain -``` - -## Docker image - -`pkg/container/base/Dockerfile` (embedded into the binary, built as `claude-env:base` by -`captain container`) builds on `flanksource/base-image` and installs a full agent toolchain: - -- **Agent CLIs** — one per backend: `claude` (`@anthropic-ai/claude-code`), `codex` - (`@openai/codex`), `gemini` (`@google/gemini-cli`), plus `tsx` for the `claude-agent` - SDK bridge -- **Flanksource tools** — `captain`, `gavel`, `repomap` (installed via `deps` from - `pkg/container/base/deps.yaml`) -- **Go** — toolchain, `task`, `ginkgo`, `golangci-lint` -- **Node** — Node.js 22, `npm`, `pnpm`, `typescript` -- **Browser automation** — `agent-browser` and Playwright Chromium (shared at - `/ms-playwright`) -- **Shell tooling** — `rg`, `fd`, `bat`, `delta`, `gh`, `jq`, `tree`, `htop`, `lsof`, - `sqlite3`, `psql`, `tmux`, `shellcheck`, `vim`, `nano`, `zsh`, `fzf`, git - -The image is set up to: - -- create a user matching host UID/GID -- switch execution using `gosu` -- use `/workspace` as the working directory - -Building it requires BuildKit. Set `GITHUB_TOKEN` (or `GH_TOKEN`) before -`captain container build` to avoid GitHub's unauthenticated API rate limit — captain passes -it through as a BuildKit secret, so it never lands in image history. To build by hand: - -```bash -DOCKER_BUILDKIT=1 docker build -t claude-env:base \ - --secret id=GITHUB_TOKEN,env=GITHUB_TOKEN \ - pkg/container/base -``` - -Publishing to `flanksource/captain` on Docker Hub and GHCR (`linux/amd64` + -`linux/arm64`) is the **Publish Image** workflow. It is manual only — dispatch it from -the tag you want to ship, and only once that tag's release exists, since the image -installs `captain` from the latest GitHub release. - -### Running a git-agent sidecar from it - -`captain sandbox git-agent deploy` enrolls an agent and places its sidecar on Docker or -Kubernetes using this image: - -```bash -captain sandbox git-agent serve --role mailbox --listen :7422 & # once, on the supervisor -captain sandbox git-agent deploy worker-01 --target docker --dry-run -captain sandbox git-agent deploy worker-01 --target docker -``` - -It applies by default; `--dry-run` prints every intended mutation first. Before minting -anything it proves a live mailbox is listening and presenting this host's own key, then -resolves the two addresses the protocol needs in opposite directions — the one the agent -reaches the mailbox on, and the one the supervisor dispatches back to. Leaving either to -be derived produces an agent that enrols, looks healthy in `git-agent list`, and fails at -the first dispatch, so `deploy` refuses rather than guesses. For `--target kubernetes` -that means `--supervisor-address` is required unless captain is itself running in the -cluster: a laptop is not routable from a managed cluster. - -The sidecar runs unprivileged (uid 501, all capabilities dropped, no privilege -escalation, read-only root with scratch on `/tmp`) and never receives a container runtime -socket — that would be a full host escape, and there is no flag to grant one. Sizing is -`--cpu-limit` / `--memory-limit` / `--storage`; the image is `--image`. The captain token -reaches the workload as a mounted file, never in argv, and `undeploy` tears the workload -down and revokes both the key and the token together. - -### Over HTTPS, with no separate mailbox process - -The mailbox can be hosted on the ordinary `captain serve` instead of its own SSH -listener. That is the process holding the database the tokens live in, so one server -serves the API, the UI and the git endpoint: - -```bash -captain serve --host 0.0.0.0 --tls --tls-host supervisor.internal # supervisor -captain sandbox git-agent add worker-01 --endpoint https://supervisor.internal:9020 -# run the printed join command on the agent host -``` - -`--tls` generates a self-signed certificate beside the git-agent keys and reuses it; -`--tls-cert` / `--tls-key` supply a real one instead. The certificate is never silently -re-issued, because every enrolled agent pins it — a certificate that does not cover an -address you name with `--tls-host` is an error at startup rather than a push failure -weeks later. An enrolling agent receives that certificate over the exchange it already -pinned, and verifies later relays against it. - -Requests from `127.0.0.1` need no token, so the local UI, CLI and hooks are unaffected; -anything off-box needs one. See `captain token` to mint, list and revoke them. Two -scopes exist: `git` reaches the push endpoint only, and `api` reaches the command API — -an agent gets `git`, so a leaked agent token cannot run commands on the supervisor. - -Tokens are durable rather than single-use, which is what lets a restarting or rescheduled -sidecar re-present the one it already has. `captain sandbox git-agent add --pool ---max-agents 5` mints one token that names each member as it arrives, for a scaled -deployment; members of a pool share a secret, so a token bound to a single agent remains -the default and stronger choice. - -## Sandbox credentials - -A sandbox needs a way to reach a model provider. An API key can simply be passed through, -but a **subscription** login cannot: Claude Code keeps its OAuth credential in the macOS -Keychain (item `Claude Code-credentials`) or `~/.claude/.credentials.json`, and Codex keeps -a ChatGPT-plan credential in `~/.codex/auth.json`, which has no env-var form at all. - -`captain sandbox credentials` mirrors those logins **with the refresh token stripped**, so a -sandbox holds an access token it can use but cannot use to mint another. For Claude that -also drops the entire `mcpOAuth` map, which holds unrelated client secrets for every MCP -server the user has authorized. - -```bash -captain sandbox credentials status # expiry per provider, and where it publishes -captain sandbox credentials sync --directory ~/.captain/sandbox/credentials -captain sandbox credentials sync --namespace agents # into a Kubernetes Secret -``` - -Because the copy cannot refresh itself, the supervisor has to. `captain serve` runs a -republish loop whose schedule comes from the credential's own expiry rather than a fixed -interval, so what lands in the target is as fresh as the host can make it. An -already-expired source is refused rather than published — a dead token in a Secret would -surface as an unexplained `401` inside an agent instead of an error where it was caused. -The host CLIs refresh their own tokens when used, so the fix is to use them. - -```yaml -# ~/.captain.yaml — publishing is opt-in; with no entries nothing is mirrored -credentials: - refreshMargin: 5m - publish: - - providers: [claude, codex] - directory: ~/.captain/sandbox/credentials # docker bind-mounts this - - providers: [claude, codex] - kubernetes: { namespace: agents, secret: captain-agent-credentials } -``` - -Local `srt` and `container` sandboxes consume the same credentials through the backend's -`tokens:` block, which also finally makes the cloud providers beside them take effect: - -```yaml -sandbox: - backends: - local: - kind: srt - tokens: { claude: {}, codex: {}, github: {} } -``` - -The redacted copy lands in a private directory and the CLI is pointed at it with -`CLAUDE_CONFIG_DIR` / `CODEX_HOME`. Once that replacement exists the host's own credential -file is added to the sandbox's deny-read list, so the sandboxed CLI can no longer reach the -refresh token — only the credential file, not the whole state directory, since the CLI still -needs its own settings and history. - -A deployed sidecar receives the Secret as a read-only **directory** mount at -`/run/captain/credentials` (`--credentials-secret`, or `--credentials-dir` for docker) and -copies each credential to the path its CLI reads. The mount is a directory rather than a -`subPath` deliberately: kubelet never updates a `subPath` volume after the pod starts, which -would pin the sidecar to the first credential it ever saw. The Secret is shared across every -agent in the namespace, so `undeploy` leaves it alone. - -## Dependencies and stack - -Primary stack: - -- **Go 1.25.8** -- **Cobra** for CLI wiring -- **clicky** for formatting/output/flag binding -- **charmbracelet/huh** for the interactive `configure` TUI -- **sandbox-runtime** for sandbox preset handling -- AI SDKs for Anthropic, OpenAI, and Gemini/Google -- shell parsing via `mvdan.cc/sh/v3` - -## Quick start - -```bash -cd captain -make build -.bin/captain info -.bin/captain history --summary -.bin/captain changes -.bin/captain container list -``` - -Configure defaults: +`make` forwards to [Taskfile.yaml](Taskfile.yaml). Build writes `.bin/captain`; install uses `go install` and its configured Go bin directory. Rebuild `task www:build` before the Go binary when changing embedded UI assets. `task www:dev` starts the Go-backed Vite development proxy. -```bash -.bin/captain configure -.bin/captain whoami -``` - -If you want to use hooks: - -```bash -.bin/captain hook bash-check install --user -.bin/captain hook monitor install -# Opt in to Claude CLI estimate capture: -.bin/captain hook monitor install --capture-cost -``` - -`--capture-cost` is opt-in because it configures a Claude Code custom status -line, with Claude's normal custom-status-line UI effects. Captain composes with -an existing status-line command and captures `cost.total_cost_usd` as Claude's -client-side session estimate. It is never attributed to model calls or written -as provider-reported billing. If the current project defines a higher-precedence -`.claude/settings.json` or `.claude/settings.local.json` status line, installation -fails rather than silently configuring an overridden user command. Without the -flag, monitor installation changes only the existing lifecycle hooks and Codex -notify configuration. Ordinary Claude transcripts and Codex's local artifacts -do not expose a monetary total, so those histories keep Captain's token-based -list-price estimate. - -Start the web UI: - -```bash -.bin/captain serve -``` - -## Notes - -- Captain is tightly focused on **Claude Code workflows**. -- It is both an analysis tool and an execution/control tool. -- The container/sandbox functionality is a major part of the project, not a side feature. -- Many commands assume the presence of Claude local state under the user’s Claude config/projects directories. -- Runtime defaults are persisted to `~/.captain.yaml`; validated provider tokens are persisted separately to the private `~/.config/captain/vault` file. +```sh +task docs:dev +task docs:build +pnpm --dir docs check +``` + +The Astro site covers prompts, runtime composition, approvals, verification, sessions, server configuration, fixtures, sandboxes and the Gavel integration. Start at [the documentation overview](docs/src/pages/index.mdx). Source docs and examples should match the current generated CLI/schema; historical designs in `docs/plans` remain design records. + +## Source layout + +| Path | Owns | +| --- | --- | +| `cmd/captain` | CLI wiring | +| `pkg/api` | Typed runtime, approval and verification contracts | +| `pkg/ai` | Providers, model catalog, prompt rendering, agent loop and middleware | +| `pkg/promptrun` | Execution admission, run lifecycle and recording | +| `pkg/runtimeprofiles` | Preset catalogs and layered composition | +| `pkg/session`, `pkg/claude` | Unified sessions and transcript parsing | +| `pkg/database`, `migrations` | PostgreSQL storage and migrations | +| `pkg/cli`, `pkg/cli/webapp` | Command handlers and embedded React UI | +| `pkg/captainconfig` | Saved defaults and credential publishing configuration | +| `pkg/sandbox`, `pkg/container`, `pkg/gitagent` | Isolation and remote execution | +| `pkg/bash`, `pkg/cmux` | Shell classification and terminal integration | +| `docs` | Astro documentation | diff --git a/docs/plans/unified-approval-callback-examples.md b/docs/plans/unified-approval-callback-examples.md index 351099a7..20fa8b2e 100644 --- a/docs/plans/unified-approval-callback-examples.md +++ b/docs/plans/unified-approval-callback-examples.md @@ -1,5 +1,7 @@ # Unified approval callback: request examples +These are design-time evidence and protocol examples, not a current runtime capability catalog. Findings labelled G19/G20 describe the pre-migration implementation. See [Approvals](../src/pages/agents/approvals.mdx) for current behavior and migration guidance. + This is a companion to [unified-approval-callback.md](unified-approval-callback.md). It shows how each approval kind reaches `Config.OnApproval`: - the native request as it arrives diff --git a/docs/plans/unified-approval-callback.md b/docs/plans/unified-approval-callback.md index 8174bce0..7a31f6a9 100644 --- a/docs/plans/unified-approval-callback.md +++ b/docs/plans/unified-approval-callback.md @@ -1,5 +1,7 @@ # Unified approval callback +This is the design and implementation record, including rollout checklists and deferred removal work. For the current public contract, broker fields and terminal behavior, see [Approvals](../src/pages/agents/approvals.mdx). Historical findings below describe the state observed during the design review. + ## Summary Extend Captain's existing `CanUseTool` callback in place, so that one callback carries execution approvals, clarification questions, and MCP elicitation, and give it a name that says so. diff --git a/pkg/ai/prompt/README.md b/pkg/ai/prompt/README.md index 76bbb939..8aad6fa2 100644 --- a/pkg/ai/prompt/README.md +++ b/pkg/ai/prompt/README.md @@ -34,7 +34,7 @@ go test ./pkg/ai -run '^TestAttachmentCapabilities$' -ginkgo.focus='Named prompt Set `DEEPSEEK_API_KEY`, then attach an existing image to a prompt: ```sh -captain prompt run --model api:deepseek-flash --attach chart.png "Describe this chart." +captain prompt run --model api:deepseek-flash --attach chart.png -p "Describe this chart." ``` For Go callers, put references in `Spec.Prompt.Attachments` or user-message attachment parts and resolve them with the attachment store before execution. Captain sends prepared images inline through the existing OpenAI-compatible Chat Completions endpoint; it does not upload them to DeepSeek's Files API. diff --git a/pkg/runtimeprofiles/README.md b/pkg/runtimeprofiles/README.md index 68a431e9..1c91f0fb 100644 --- a/pkg/runtimeprofiles/README.md +++ b/pkg/runtimeprofiles/README.md @@ -1,4 +1,6 @@ -# Runtime profile composition +# Runtime preset composition + +Select reusable layers with presets. `RequestedProfile`, `PinnedProfile`, `DefaultProfile`, prompt `runtimeProfile` and CLI `--runtime-profile` are deprecated: the resolver emits a warning and contributes no profile layers. Use `RequestedPresets` (or frontmatter `presets` / CLI `--preset`) instead. Use `Catalog.Layers` or `Resolver.Layers` to load reusable configuration before adding a prompt and request. They validate authored structures without choosing a model or checking a guessed runtime. A profile can contain only permissions, mode, effort, or budget; a later request can supply or replace its runtime. @@ -6,7 +8,7 @@ Validate each owner's raw layers with `api.ValidateSpecLayers` before combining ```go layers, err := resolver.Layers(ctx, runtimeprofiles.ResolveOptions{ - RequestedProfile: "review", + RequestedPresets: []string{"Plan"}, SurfaceLayers: []api.SpecLayer{ api.PromptSpecLayer("review.prompt", document.Spec), }, @@ -46,7 +48,7 @@ Malformed saved declarations fail before a request can hide them and return `*ap Layer resolution checks every declared primary and fallback runtime. Execution preflight separately checks the enabled candidates selected for the actual provider configuration. Disabling a candidate for one execution does not make an unsupported sandbox or tool policy valid in the declared profile. -Catalog failures preserve ownership: `*runtimeprofiles.OwnedLayersError` wraps invalid stored data and missing nested preset references. An absent or ambiguous top-level profile remains `ErrNotFound` or `ErrAmbiguous`. `Resolver` additionally wraps selection failures in `*SelectionError`, recording whether the request, prompt pin, or configured default selected the profile. Use `errors.As` and `errors.Is` instead of parsing error text. +Catalog failures preserve ownership: `*runtimeprofiles.OwnedLayersError` wraps invalid stored data and missing nested preset references. An absent or ambiguous top-level selection remains `ErrNotFound` or `ErrAmbiguous`. `Resolver` additionally wraps selection failures in `*SelectionError`, recording whether the request, prompt pin, or configured default selected the presets. Use `errors.As` and `errors.Is` instead of parsing error text. ## Preset order From dd72d078fb63b9d41e5915b83445f1e3ac309f47 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Thu, 22 Oct 2026 22:56:07 +0300 Subject: [PATCH 18/77] chore: update generated and lock files --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 13910f24..7e46ff12 100644 --- a/.gitignore +++ b/.gitignore @@ -37,3 +37,4 @@ hack/* !pkg/cli/webapp/dist/index.html *.test .codegraph/ +/assets/brand/captain-formation/presentation/ From ae84cd602444a98297cb33cd2eaa4b5509be3880 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Thu, 22 Oct 2026 22:59:56 +0300 Subject: [PATCH 19/77] fix(cli): keep main.go self-contained so go run ./main.go compiles Move the promptfile lint command into the rootcmd package; main.go referenced a symbol from a sibling file, breaking the standalone entrypoint spec. Also discard the unused String() result flagged by go vet in the version spec. --- cmd/captain/{ => internal/rootcmd}/lint.go | 4 ++-- cmd/captain/main.go | 2 +- cmd/captain/version_test.go | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) rename cmd/captain/{ => internal/rootcmd}/lint.go (95%) diff --git a/cmd/captain/lint.go b/cmd/captain/internal/rootcmd/lint.go similarity index 95% rename from cmd/captain/lint.go rename to cmd/captain/internal/rootcmd/lint.go index 6e26569a..ef0d6e40 100644 --- a/cmd/captain/lint.go +++ b/cmd/captain/internal/rootcmd/lint.go @@ -1,4 +1,4 @@ -package main +package rootcmd import ( "context" @@ -20,7 +20,7 @@ type promptfileLintOptions struct { Vars string `flag:"vars" clicky:"cli-file-read" help:"Sample template inputs as a JSON object, or @file"` } -func registerLintCommand(root *cobra.Command) { +func RegisterLintCommand(root *cobra.Command, isStdinAvailable func() bool) { parent := &cobra.Command{Use: "lint", Short: "Validate Captain configuration files"} clicky.MarkLocalOnly(parent) root.AddCommand(parent) diff --git a/cmd/captain/main.go b/cmd/captain/main.go index c1e4c0be..8019e150 100644 --- a/cmd/captain/main.go +++ b/cmd/captain/main.go @@ -143,7 +143,7 @@ func newRootCommand() *cobra.Command { clicky.AddNamedCommandWithContext("tokens", sessionsCmd, cli.SessionTokensOptions{}, cli.RunSessionTokens).Short = "Size canonical transcript rows without changing recorded usage" rootCmd.AddCommand(cli.NewBrowserCommand()) - registerLintCommand(rootCmd) + rootcmd.RegisterLintCommand(rootCmd, isStdinAvailable) psCmd := clicky.AddNamedCommandWithContext("ps", rootCmd, cli.PSOptions{}, cli.RunPS) psCmd.Short = "List live agent sessions, or inspect specific process IDs" diff --git a/cmd/captain/version_test.go b/cmd/captain/version_test.go index 24080e13..0cfc4fd2 100644 --- a/cmd/captain/version_test.go +++ b/cmd/captain/version_test.go @@ -35,7 +35,7 @@ var _ = Describe("version information", func() { info := rootcmd.BuildInfo{Version: "v1.2.3", Commit: "abc1234", Date: "2026-07-27T12:34:56Z", Dirty: "maybe"} Expect(func() { - info.String() + _ = info.String() }).To(PanicWith(`invalid build dirty state "maybe"`)) }) From 5fe62a5f29b55239270e57e39738d00bbdc97af4 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Fri, 23 Oct 2026 16:05:37 +0300 Subject: [PATCH 20/77] feat(adapters): add native resource schemas and validation to adapter catalog Expose native provider configuration, reusable resource definitions and Captain portable and backend configuration alongside the execution schemas. Each catalog document gains a stable id and kind. Execution modes and existing URLs are unchanged. Add a stateless POST /api/captain/ai/adapter-schemas/validate endpoint. It compiles local references only and returns instancePath and schemaPath errors without resolving, executing or persisting anything. Generated OpenAI agent request types move to OpenAIAgentOptions* names, and union fields keep their JSON marshaling. Form annotations (help links, enum labels and icons, typed JSON editors) are generated from pinned sources by hack/adapterresources. BREAKING CHANGE: GET adapter-schemas now also returns resource documents. Clients must key on id and kind rather than assuming a provider/mode pair. Go types ThreadStart, ThreadResume and TurnStart are renamed to OpenAIAgentOptionsThreadStart, OpenAIAgentOptionsThreadResume and OpenAIAgentOptionsTurnStart. Claude-Session-Id: b00416a9-facd-49f8-9bc6-cd4ef7eba6b4 --- .gitignore | 3 + docs/adapter-resource-schemas.md | 59 ++++++ docs/plans/adapter-resource-schemas.md | 23 +++ hack/adapterbrowser/main.go | 61 ++++++ hack/adapterdto/main.go | 46 +++++ hack/adapterresources/claude-types.ts | 11 + hack/adapterresources/cli.go | 59 ++++++ hack/adapterresources/execution.go | 38 ++++ hack/adapterresources/main.go | 94 +++++++++ hack/adapterresources/permissions.go | 22 ++ hack/adapterresources/runtime.go | 170 +++++++++++++++ hack/adapterresources/sdk.go | 195 ++++++++++++++++++ hack/adapterresources/sdk_source.go | 81 ++++++++ pkg/adapters/arbitrary_json_ginkgo_test.go | 35 ++++ pkg/adapters/backend_resources.go | 49 +++++ pkg/adapters/catalog.go | 17 +- pkg/adapters/generate.go | 23 ++- pkg/adapters/nested_resources_ginkgo_test.go | 22 ++ pkg/adapters/presentation/presentation.go | 178 ++++++++++++++++ .../resource_annotations_ginkgo_test.go | 78 +++++++ pkg/adapters/resource_catalog.go | 163 +++++++++++++++ pkg/adapters/resource_references.go | 44 ++++ pkg/adapters/resources/README.md | 3 + pkg/adapters/resources/captain-backends.json | 50 +++++ .../resources_contract_ginkgo_test.go | 95 +++++++++ pkg/adapters/schema_contract_ginkgo_test.go | 15 +- pkg/adapters/validation.go | 85 ++++++++ 27 files changed, 1696 insertions(+), 23 deletions(-) create mode 100644 docs/adapter-resource-schemas.md create mode 100644 docs/plans/adapter-resource-schemas.md create mode 100644 hack/adapterbrowser/main.go create mode 100644 hack/adapterdto/main.go create mode 100644 hack/adapterresources/claude-types.ts create mode 100644 hack/adapterresources/cli.go create mode 100644 hack/adapterresources/execution.go create mode 100644 hack/adapterresources/main.go create mode 100644 hack/adapterresources/permissions.go create mode 100644 hack/adapterresources/runtime.go create mode 100644 hack/adapterresources/sdk.go create mode 100644 hack/adapterresources/sdk_source.go create mode 100644 pkg/adapters/arbitrary_json_ginkgo_test.go create mode 100644 pkg/adapters/backend_resources.go create mode 100644 pkg/adapters/nested_resources_ginkgo_test.go create mode 100644 pkg/adapters/presentation/presentation.go create mode 100644 pkg/adapters/resource_annotations_ginkgo_test.go create mode 100644 pkg/adapters/resource_catalog.go create mode 100644 pkg/adapters/resource_references.go create mode 100644 pkg/adapters/resources/README.md create mode 100644 pkg/adapters/resources/captain-backends.json create mode 100644 pkg/adapters/resources_contract_ginkgo_test.go create mode 100644 pkg/adapters/validation.go diff --git a/.gitignore b/.gitignore index 7e46ff12..3a143c5d 100644 --- a/.gitignore +++ b/.gitignore @@ -31,6 +31,9 @@ hack/ !hack/ hack/* !hack/gitagent_empirical.sh +!hack/adapterresources/ +!hack/adapterdto/ +!hack/adapterbrowser/ .ok/ .okignore .ginkgo/ diff --git a/docs/adapter-resource-schemas.md b/docs/adapter-resource-schemas.md new file mode 100644 index 00000000..162e8386 --- /dev/null +++ b/docs/adapter-resource-schemas.md @@ -0,0 +1,59 @@ +# Adapter and resource schemas + +Open `/adapter-schemas` in `captain serve --dev`. Select a provider and resource to inspect its schema or edit a local Form, JSON or YAML draft. Resource selection, view and search are shareable URLs; draft values remain in the mounted page and are discarded on reload. Switching resources retains each draft. Invalid JSON/YAML stays editable and disables form editing and validation until corrected. + +“Validate schema” checks the document against its selected JSON Schema. It does not resolve profile inheritance, inspect credential files, check installed tools, enforce runtime capabilities, execute hooks or apply configuration. Execution-only managed/unsupported options and enrollment-managed agent records render read-only. Native resource schemas describe the provider's configuration independently of Captain's forwarding support. + +## Catalog + +The array returned by `GET /api/captain/ai/adapter-schemas` contains stable `id`, `kind`, `provider`, `title`, `description` and `schema` fields. Execution documents additionally carry `mode`. Existing `anthropic/api`, `openai/agent` and other execution IDs remain valid. Resource IDs include `openai/permission-profile`, `anthropic/sandbox`, `google/settings`, `captain/permissions`, `captain/preset`, `captain/docker-backend` and `captain/git-agent-backend`. + +POST a value without saving or applying it: + +```sh +curl -sS http://localhost:9020/api/captain/ai/adapter-schemas/validate \ + -H 'Content-Type: application/json' \ + -d '{"id":"openai/permission-profile","value":{"extends":"team-workspace","workspace_roots":{"/workspace":true}}}' +``` + +Errors include JSON-pointer instance and schema paths. A well-formed request with invalid values returns HTTP 200 and `valid:false`; malformed requests return 400, unknown IDs 404, and invalid catalog schemas 500. The endpoint has a 1 MiB request limit. No runtime or persistence call occurs. + +## Sources and regeneration + +Configuration snapshots record source versions, references, SHA-256 and top-level property counts in `x-captain-resource`. Execution schemas retain `x-captain-adapter` provenance, support annotations and source inventories. CLI inventories include every long option in the captured execution command help, including aliases. API inventories follow the module-pinned request types and nested definitions, preserving required fields, literal discriminators, native enums and typed maps. + +Capture source files under `.tmp/adapter-schema-sources` from the repository root: + +```sh +mkdir -p .tmp/adapter-schema-sources +curl -fL https://raw.githubusercontent.com/openai/codex/rust-v0.164.0/codex-rs/core/config.schema.json -o .tmp/adapter-schema-sources/codex-config.json +curl -fL https://raw.githubusercontent.com/google-gemini/gemini-cli/v0.64.0/schemas/settings.schema.json -o .tmp/adapter-schema-sources/gemini-settings.json +npm install --prefix .tmp/adapter-schema-sources/sdk --ignore-scripts @anthropic-ai/claude-agent-sdk@0.3.280 ts-json-schema-generator@2.9.0 +.tmp/adapter-schema-sources/sdk/node_modules/.bin/ts-json-schema-generator --path hack/adapterresources/claude-types.ts --type CaptainClaudeSettings --out .tmp/adapter-schema-sources/claude-settings.json +.tmp/adapter-schema-sources/sdk/node_modules/.bin/ts-json-schema-generator --path hack/adapterresources/claude-types.ts --type CaptainClaudeAgent --out .tmp/adapter-schema-sources/claude-agent.json +.tmp/adapter-schema-sources/sdk/node_modules/.bin/ts-json-schema-generator --path hack/adapterresources/claude-types.ts --type CaptainClaudeMCP --out .tmp/adapter-schema-sources/claude-mcp.json +.tmp/adapter-schema-sources/sdk/node_modules/.bin/ts-json-schema-generator --path hack/adapterresources/claude-types.ts --type CaptainClaudePlugin --out .tmp/adapter-schema-sources/claude-plugin.json +codex app-server generate-json-schema --experimental --out .tmp/adapter-schema-sources/codex-protocol +claude --help > .tmp/adapter-schema-sources/claude-help.txt +codex exec --help > .tmp/adapter-schema-sources/codex-help.txt +gemini --help > .tmp/adapter-schema-sources/gemini-help.txt +go run ./hack/adapterresources +go generate ./pkg/adapters +go test ./pkg/adapters/... +``` + +Use Claude CLI 2.1.309, Codex CLI 0.164.0 and Gemini CLI 0.64.0 for these captures. Review source-version changes intentionally. The importer rejects missing native root shapes and newly uncovered CLI flags. Codex's generated schema omits `serde(flatten)` permission maps; their value schemas are supplied from `codex-rs/config/src/permissions_toml.rs` at the same release, with source references on each supplemented definition. + +Captain backend JSON follows `sandbox.backends.` in `~/.captain.yaml`: `kind` and backend option keys are siblings. Docker backend volume values are strings (`source:target[:ro]`), distinct from the structured volumes in `.container-sandbox.yaml`. Git Agent enrollment entries contain endpoint trust and credential **paths**, never credential contents. Its `waitTimeout` remains subject to positive-duration validation at runtime. + +## Form annotations + +Use `title`, `description`, `x-help.links`, `x-clicky-order`, `x-clicky-section`, `x-enum-labels`, `x-enum-display`, `x-enum-icons`, `x-array-display` and `readOnly` on the owning schema nodes. Documentation links are absolute HTTP(S) URLs. Icons resolve through Clicky UI's offline icon provider. Presentation annotations do not replace validation constraints or native wire names. + +Clicky UI renders object/array/scalar unions with a branch selector and retains branch drafts. `format:json` explicitly requests a typed JSON editor for genuinely arbitrary JSON. Typed `additionalProperties` and `patternProperties` remain editable maps; recursive references are kept in the schema graph rather than expanded indefinitely. Native source schemas can evolve independently of Captain's executable option coverage. + +## Live form smoke check + +With the development server on port 9020, run `go run ./hack/adapterbrowser`. It uses `agent-browser --engine chrome --session captain-adapters-impl` to open every live catalog document in Form view, verifies the local-preview and validation controls, and fails on a render error. It does not change resource values or apply configuration. Close that browser session after inspection with `agent-browser --engine chrome --session captain-adapters-impl close`. + +The expansion was checked against all 50 live form views, JSON/YAML draft retention and correction, server-side nested permission errors, documentation links and offline enum icons, plus desktop and 390px compact layouts. Focused Go contract/API tests, 485 shared form tests, Captain UI tests, scoped lint, Go and Clicky builds, and repeated-generation hashes passed. Repository-wide lint encounters unrelated duplicate `main` declarations under `hack/`; the production webapp build encounters the existing `RuntimePreset.order` mismatch with the pinned published Clicky package. The shared form improvements live in the sibling Clicky UI checkout and need its normal release/dependency update before shipping. diff --git a/docs/plans/adapter-resource-schemas.md b/docs/plans/adapter-resource-schemas.md new file mode 100644 index 00000000..866f122e --- /dev/null +++ b/docs/plans/adapter-resource-schemas.md @@ -0,0 +1,23 @@ +# Adapter resource schema expansion + +Status: implemented; final validation recorded in the execution report. + +## Approved scope + +Expand all registered API, Agent and CLI execution schemas and expose native provider configuration and reusable resources alongside portable Captain configuration. Include sandbox policies, named permission profiles, filesystem and network grants, hooks, MCP, agents, skills, plugins, model/environment settings and trusted Docker/Git Agent backend configuration. Keep provider execution wiring unchanged. + +Expose a stable resource ID and kind on each catalog document, retain existing execution modes and URLs, and provide stateless schema validation. Compile local references without fetching external schemas. Preserve source versions and native constraints. + +Use shared Clicky UI form annotations and controls for editing, enums, enum icons, documentation links, typed maps and unions. Offer Schema, Form, JSON and YAML views with independent local drafts per resource, recoverable malformed source and explicit schema validation. Selection, search and view belong in the URL. Drafts are local preview state and have no save/apply action. + +## Implementation + +`pkg/adapters/resources` contains pinned native source snapshots. The resource catalog projects reusable definitions with their transitive local references. Captain resources derive from the owning Go API models; trusted backend shapes follow their adapter option readers. `hack/adapterresources` imports pinned sources, completes Rust flatten-map declarations and annotates the schema graph without changing native enum values. Generated DTO union aliases preserve JSON marshaling methods. + +The existing GET endpoint returns the expanded array. POST `/api/captain/ai/adapter-schemas/validate` takes `{id,value}` and returns `valid` and structured errors containing `instancePath`, `schemaPath` and `message`. Malformed requests return 400, unknown IDs return 404 and schema compilation failures return 500. + +## Verification + +Contract tests cover the complete registry matrix, source inventory, recursive annotations, self-contained schema compilation, invalid nested permissions and native DTO round trips. UI tests cover union selection, typed JSON, help links and independent recoverable resource drafts. Verify generation twice, focused Go and Vitest suites, Clicky UI check/build, Captain lint/build, and the exact development route in Chrome at desktop and compact widths. + +See [the resource guide](../adapter-resource-schemas.md) for source capture, validation examples and operating limits. diff --git a/hack/adapterbrowser/main.go b/hack/adapterbrowser/main.go new file mode 100644 index 00000000..4f81c0ca --- /dev/null +++ b/hack/adapterbrowser/main.go @@ -0,0 +1,61 @@ +// adapterbrowser smoke-checks every live catalog resource through agent-browser. +package main + +import ( + "context" + "encoding/json" + "fmt" + "net/http" + "net/url" + "os/exec" + "strings" + "time" +) + +func main() { + response, err := (&http.Client{Timeout: 20 * time.Second}).Get("http://localhost:9020/api/captain/ai/adapter-schemas") + check(err) + defer response.Body.Close() + if response.StatusCode != http.StatusOK { + panic(response.Status) + } + var documents []struct { + ID string `json:"id"` + } + check(json.NewDecoder(response.Body).Decode(&documents)) + if len(documents) == 0 { + panic("empty resource catalog") + } + for _, document := range documents { + parts := strings.SplitN(document.ID, "/", 2) + if len(parts) != 2 { + panic("invalid resource id: " + document.ID) + } + location := "http://localhost:9020/adapter-schemas/" + url.PathEscape(parts[0]) + "/" + url.PathEscape(parts[1]) + "?view=form" + browser("open", location) + browser("wait", "--text", "Local preview.") + body := browser("get", "text", "body") + if strings.Contains(body, "Something went wrong") || !strings.Contains(body, "Validate schema") { + panic(fmt.Sprintf("%s form failed: %s", document.ID, body)) + } + fmt.Println("PASS " + document.ID) + } + fmt.Printf("PASS all %d resource forms\n", len(documents)) +} + +func browser(args ...string) string { + ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) + defer cancel() + command := exec.CommandContext(ctx, "agent-browser", append([]string{"--engine", "chrome", "--session", "captain-adapters-impl"}, args...)...) + raw, err := command.CombinedOutput() + if err != nil { + panic(fmt.Sprintf("agent-browser %v: %v\n%s", args, err, raw)) + } + return string(raw) +} + +func check(err error) { + if err != nil { + panic(err) + } +} diff --git a/hack/adapterdto/main.go b/hack/adapterdto/main.go new file mode 100644 index 00000000..04efc5cd --- /dev/null +++ b/hack/adapterdto/main.go @@ -0,0 +1,46 @@ +// adapterdto preserves encoding/json's methods on generated native union types. +package main + +import ( + "go/ast" + "go/format" + "go/parser" + "go/token" + "os" + "path/filepath" +) + +func main() { + paths, err := filepath.Glob("zz_generated_*.go") + check(err) + for _, path := range paths { + set := token.NewFileSet() + file, err := parser.ParseFile(set, path, nil, parser.ParseComments) + check(err) + ast.Inspect(file, func(node ast.Node) bool { + declaration, ok := node.(*ast.TypeSpec) + if !ok { + return true + } + selector, ok := declaration.Type.(*ast.SelectorExpr) + if !ok { + return true + } + qualifier, ok := selector.X.(*ast.Ident) + if ok && qualifier.Name == "json" && selector.Sel.Name == "RawMessage" { + declaration.Assign = declaration.Name.End() + } + return true + }) + output, err := os.Create(path) + check(err) + check(format.Node(output, set, file)) + check(output.Close()) + } +} + +func check(err error) { + if err != nil { + panic(err) + } +} diff --git a/hack/adapterresources/claude-types.ts b/hack/adapterresources/claude-types.ts new file mode 100644 index 00000000..7b60cb87 --- /dev/null +++ b/hack/adapterresources/claude-types.ts @@ -0,0 +1,11 @@ +import type { + Settings, + AgentDefinition, + McpServerConfigForProcessTransport, + SdkPluginConfig, +} from "../../.tmp/adapter-schema-sources/sdk/node_modules/@anthropic-ai/claude-agent-sdk/sdk"; + +export type CaptainClaudeSettings = Settings; +export type CaptainClaudeAgent = AgentDefinition; +export type CaptainClaudeMCP = McpServerConfigForProcessTransport; +export type CaptainClaudePlugin = SdkPluginConfig; diff --git a/hack/adapterresources/cli.go b/hack/adapterresources/cli.go new file mode 100644 index 00000000..4ba61e45 --- /dev/null +++ b/hack/adapterresources/cli.go @@ -0,0 +1,59 @@ +package main + +import ( + "fmt" + "os" + "regexp" + "sort" + "strings" +) + +func inventoryCLIOptions() { + flagLine := regexp.MustCompile(`^ {2,6}(?:-[a-zA-Z],\s+)?--[a-zA-Z]`) + longFlag := regexp.MustCompile(`--[a-zA-Z][a-zA-Z0-9-]*`) + for _, provider := range []struct{ name, help, version string }{ + {"anthropic", "claude", "claude-cli 2.1.309"}, + {"openai", "codex", "codex-cli 0.164.0"}, + {"google", "gemini", "gemini-cli 0.64.0"}, + } { + raw, err := os.ReadFile(".tmp/adapter-schema-sources/" + provider.help + "-help.txt") + must(err) + path := "pkg/adapters/" + provider.name + "/cli.schema.json" + schema := readObject(path) + mapped := map[string]map[string]any{} + for _, raw := range schema["properties"].(map[string]any) { + field := raw.(map[string]any) + option := field["x-captain-option"].(map[string]any) + mapped[option["nativeName"].(string)] = option + } + var flags, missing []string + for _, line := range strings.Split(string(raw), "\n") { + if !flagLine.MatchString(line) { + continue + } + header := strings.SplitN(strings.TrimSpace(line), " ", 2)[0] + aliases := longFlag.FindAllString(header, -1) + var option map[string]any + for _, name := range aliases { + if mapped[name] != nil { + option = mapped[name] + break + } + } + if option == nil { + missing = append(missing, aliases[0]) + continue + } + if len(aliases) > 1 { + option["aliases"] = aliases + } + flags = append(flags, aliases...) + } + if len(missing) > 0 { + panic(fmt.Sprintf("%s CLI flags missing: %v", provider.name, missing)) + } + sort.Strings(flags) + schema["x-captain-inventory"] = map[string]any{"version": provider.version, "flags": flags} + writeObject(path, schema) + } +} diff --git a/hack/adapterresources/execution.go b/hack/adapterresources/execution.go new file mode 100644 index 00000000..8a5ca1c6 --- /dev/null +++ b/hack/adapterresources/execution.go @@ -0,0 +1,38 @@ +package main + +import ( + "path/filepath" + "strings" + + "github.com/flanksource/captain/pkg/adapters/presentation" +) + +func annotateExecutionSchemas() { + paths, err := filepath.Glob("pkg/adapters/*/*.schema.json") + must(err) + for _, path := range paths { + schema := readObject(path) + provider := schema["x-captain-adapter"].(map[string]any)["provider"].(string) + mode := schema["x-captain-adapter"].(map[string]any)["mode"].(string) + schema["title"] = presentation.Title(provider) + " " + presentation.Title(mode) + " options" + docs := map[string]string{ + "anthropic": "https://code.claude.com/docs/en/settings-reference", + "openai": "https://learn.chatgpt.com/docs/config-file/config-reference", + "google": "https://geminicli.com/docs/reference/configuration/", + "deepseek": "https://api-docs.deepseek.com/api/create-chat-completion/", + "jev": "https://github.com/flanksource/captain", + }[provider] + presentation.AnnotateSchema(schema, docs) + markNativeUnions(schema) + if strings.HasSuffix(path, "cli.schema.json") { + versions := map[string]string{"anthropic": "2.1.309", "openai": "codex-cli 0.164.0", "google": "0.64.0"} + for _, raw := range schema["x-captain-adapter"].(map[string]any)["sources"].([]any) { + source := raw.(map[string]any) + if source["kind"] == "cli-help" { + source["version"] = versions[provider] + } + } + } + writeObject(path, schema) + } +} diff --git a/hack/adapterresources/main.go b/hack/adapterresources/main.go new file mode 100644 index 00000000..ffda798b --- /dev/null +++ b/hack/adapterresources/main.go @@ -0,0 +1,94 @@ +package main + +import ( + "crypto/sha256" + "encoding/json" + "fmt" + "os" + "strings" + + "github.com/flanksource/captain/pkg/adapters/presentation" +) + +func main() { + for _, source := range []struct{ provider, file, version, reference, docs string }{ + {"openai", "codex-config.json", "codex-cli 0.164.0", "https://raw.githubusercontent.com/openai/codex/rust-v0.164.0/codex-rs/core/config.schema.json", "https://learn.chatgpt.com/docs/config-file/config-reference"}, + {"anthropic", "claude-settings.json", "@anthropic-ai/claude-agent-sdk 0.3.280; ts-json-schema-generator 2.9.0", "@anthropic-ai/claude-agent-sdk/sdk.d.ts#Settings", "https://code.claude.com/docs/en/settings-reference"}, + {"google", "gemini-settings.json", "gemini-cli 0.64.0", "https://raw.githubusercontent.com/google-gemini/gemini-cli/v0.64.0/schemas/settings.schema.json", "https://geminicli.com/docs/reference/configuration/"}, + } { + raw, err := os.ReadFile(".tmp/adapter-schema-sources/" + source.file) + must(err) + var schema map[string]any + must(json.Unmarshal(raw, &schema)) + flattenRoot(schema) + if source.provider == "openai" { + completePermissionMaps(schema) + } + if source.provider == "anthropic" { + mergeClaudeResources(schema) + } + properties, ok := schema["properties"].(map[string]any) + if !ok || len(properties) < 20 { + panic(fmt.Sprintf("%s has no complete native configuration: %d properties", source.provider, len(properties))) + } + schema["title"] = strings.ToUpper(source.provider[:1]) + source.provider[1:] + " configuration" + schema["description"] = "Complete native " + source.provider + " configuration captured from " + source.version + "." + schema["x-captain-resource"] = map[string]any{ + "provider": source.provider, "version": source.version, "reference": source.reference, + "sourceSha256": fmt.Sprintf("%x", sha256.Sum256(raw)), "propertyCount": len(properties), + } + schema["x-captain-generated"] = "go run ./hack/adapterresources" + presentation.AnnotateSchema(schema, source.docs) + encoded, err := json.MarshalIndent(schema, "", " ") + must(err) + must(os.WriteFile("pkg/adapters/resources/"+source.provider+".json", append(encoded, '\n'), 0o644)) + fmt.Printf("%s: %d top-level properties\n", source.provider, len(properties)) + } + enrichRuntimeSchemas() + enrichAPISchemas() + annotateExecutionSchemas() + inventoryCLIOptions() +} + +func mergeClaudeResources(schema map[string]any) { + definitions := schema["definitions"].(map[string]any) + for _, resource := range []string{"mcp", "agent", "plugin"} { + raw, err := os.ReadFile(".tmp/adapter-schema-sources/claude-" + resource + ".json") + must(err) + var extra map[string]any + must(json.Unmarshal(raw, &extra)) + for key, value := range extra["definitions"].(map[string]any) { + if existing, ok := definitions[key]; ok { + left, err := json.Marshal(existing) + must(err) + right, err := json.Marshal(value) + must(err) + if string(left) != string(right) { + panic("conflicting native definition " + key) + } + } + definitions[key] = value + } + } +} + +func flattenRoot(schema map[string]any) { + for schema["$ref"] != nil { + ref, ok := schema["$ref"].(string) + if !ok || !strings.HasPrefix(ref, "#/definitions/") { + panic(fmt.Sprintf("unexpected root reference %v", schema["$ref"])) + } + definitions := schema["definitions"].(map[string]any) + target := definitions[strings.TrimPrefix(ref, "#/definitions/")].(map[string]any) + delete(schema, "$ref") + for key, value := range target { + schema[key] = value + } + } +} + +func must(err error) { + if err != nil { + panic(err) + } +} diff --git a/hack/adapterresources/permissions.go b/hack/adapterresources/permissions.go new file mode 100644 index 00000000..26fee271 --- /dev/null +++ b/hack/adapterresources/permissions.go @@ -0,0 +1,22 @@ +package main + +// Codex's flattened Rust maps are not emitted by schemars. These value types +// come from codex-rs/config/src/permissions_toml.rs at rust-v0.164.0. +func completePermissionMaps(schema map[string]any) { + definitions := schema["definitions"].(map[string]any) + for name, target := range map[string]string{ + "PermissionsToml": "PermissionProfileToml", + "FilesystemPermissionsToml": "FilesystemPermissionToml", + "NetworkDomainPermissionsToml": "NetworkDomainPermissionToml", + "NetworkUnixSocketPermissionsToml": "NetworkUnixSocketPermissionToml", + "WorkspaceRootsToml": "", + } { + value := map[string]any{"type": "boolean"} + if target != "" { + value = map[string]any{"$ref": "#/definitions/" + target} + } + node := definitions[name].(map[string]any) + node["additionalProperties"] = value + node["x-captain-source"] = "https://github.com/openai/codex/blob/rust-v0.164.0/codex-rs/config/src/permissions_toml.rs" + } +} diff --git a/hack/adapterresources/runtime.go b/hack/adapterresources/runtime.go new file mode 100644 index 00000000..18e74663 --- /dev/null +++ b/hack/adapterresources/runtime.go @@ -0,0 +1,170 @@ +package main + +import ( + "encoding/json" + "fmt" + "os" + "strings" + + "github.com/flanksource/captain/pkg/adapters/presentation" +) + +func enrichRuntimeSchemas() { + path := "pkg/adapters/openai/agent.schema.json" + schema := readObject(path) + definitions := map[string]any{} + properties := schema["properties"].(map[string]any) + for _, operation := range []struct{ name, file, native string }{ + {"initialize", "v1/InitializeParams", "initialize"}, + {"threadStart", "v2/ThreadStartParams", "thread/start"}, + {"threadResume", "v2/ThreadResumeParams", "thread/resume"}, + {"turnStart", "v2/TurnStartParams", "turn/start"}, + } { + native := readObject(".tmp/adapter-schema-sources/codex-protocol/" + operation.file + ".json") + renameReferences(native, "OpenAIAgent") + for key, value := range native["definitions"].(map[string]any) { + definitions["OpenAIAgent"+key] = value + } + old := properties[operation.name].(map[string]any) + for key, raw := range native["properties"].(map[string]any) { + field := raw.(map[string]any) + previous, exists := old["properties"].(map[string]any)[key].(map[string]any) + if exists { + for _, annotation := range []string{"title", "description", "x-captain-option", "readOnly", "x-clicky-section", "x-clicky-order", "x-enum-display", "x-enum-icons"} { + if value, ok := previous[annotation]; ok { + field[annotation] = value + } + } + } else { + field["readOnly"] = true + field["x-clicky-section"] = "cli" + field["x-captain-option"] = map[string]any{"nativeName": operation.native + "." + key, + "support": "unsupported", "note": "Accepted by the native protocol; Captain does not construct this option."} + } + } + old["properties"] = native["properties"] + delete(old, "required") + if required, ok := native["required"]; ok { + old["required"] = required + } + } + schema["$defs"] = definitions + sources := schema["x-captain-adapter"].(map[string]any)["sources"].([]any) + for _, raw := range sources { + source := raw.(map[string]any) + if source["kind"] == "protocol" { + source["version"] = "codex-cli 0.164.0" + } + } + presentation.AnnotateSchema(schema, "https://learn.chatgpt.com/docs/developers/app-server") + markNativeUnions(schema) + writeObject(path, schema) + enrichClaudeRuntime() +} + +func enrichClaudeRuntime() { + source := readObject("pkg/adapters/resources/anthropic.json") + definitions := source["definitions"].(map[string]any) + settings := definitions["Settings"].(map[string]any) + path := "pkg/adapters/anthropic/agent.schema.json" + schema := readObject(path) + props := schema["properties"].(map[string]any) + for _, mapping := range []struct{ property, definition string }{ + {"sandbox", ""}, {"settings", "Settings"}, {"managedSettings", "Settings"}, + {"agents", "AgentDefinition"}, {"mcpServers", "McpServerConfigForProcessTransport"}, + } { + field := props[mapping.property].(map[string]any) + var native map[string]any + if mapping.property == "sandbox" { + native = settings["properties"].(map[string]any)["sandbox"].(map[string]any) + } else if mapping.property == "agents" || mapping.property == "mcpServers" { + native = map[string]any{"type": "object", "additionalProperties": map[string]any{"$ref": "#/definitions/" + mapping.definition}} + } else { + native = map[string]any{"$ref": "#/definitions/" + mapping.definition} + } + delete(field, "additionalProperties") + for key, value := range native { + field[key] = value + } + } + schema["definitions"] = definitions + renameReferences(schema, "AnthropicAgent") + renamed := map[string]any{} + for key, value := range definitions { + renamed["AnthropicAgent"+key] = value + } + delete(schema, "definitions") + schema["$defs"] = renamed + presentation.AnnotateSchema(schema, "https://platform.claude.com/docs/en/agent-sdk/typescript") + markNativeUnions(schema) + writeObject(path, schema) +} + +func renameReferences(raw any, prefix string) { + switch node := raw.(type) { + case map[string]any: + if ref, ok := node["$ref"].(string); ok && strings.HasPrefix(ref, "#/definitions/") { + node["$ref"] = "#/$defs/" + prefix + strings.TrimPrefix(ref, "#/definitions/") + } + for _, child := range node { + renameReferences(child, prefix) + } + case []any: + for _, child := range node { + renameReferences(child, prefix) + } + } +} + +func markNativeUnions(raw any) { + switch node := raw.(type) { + case map[string]any: + _, oneOf := node["oneOf"].([]any) + _, anyOf := node["anyOf"].([]any) + if oneOf || anyOf { + node["goJSONSchema"] = map[string]any{"type": "json.RawMessage", "imports": []any{"encoding/json"}} + } + for _, child := range node { + markNativeUnions(child) + } + case []any: + for _, child := range node { + markNativeUnions(child) + } + } +} + +func readObject(path string) map[string]any { + raw, err := os.ReadFile(path) + must(err) + var schema map[string]any + must(json.Unmarshal(raw, &schema)) + return schema +} + +func writeObject(path string, value map[string]any) { + clearFieldIdentifiers(value) + raw, err := json.MarshalIndent(value, "", " ") + must(err) + must(os.WriteFile(path, append(raw, '\n'), 0o644)) + fmt.Println("Updated " + path) +} + +func clearFieldIdentifiers(raw any) { + switch node := raw.(type) { + case map[string]any: + if extension, ok := node["goJSONSchema"].(map[string]any); ok { + delete(extension, "identifier") + if len(extension) == 0 { + delete(node, "goJSONSchema") + } + } + for _, child := range node { + clearFieldIdentifiers(child) + } + case []any: + for _, child := range node { + clearFieldIdentifiers(child) + } + } +} diff --git a/hack/adapterresources/sdk.go b/hack/adapterresources/sdk.go new file mode 100644 index 00000000..511eaf00 --- /dev/null +++ b/hack/adapterresources/sdk.go @@ -0,0 +1,195 @@ +package main + +import ( + "encoding/json" + "fmt" + "reflect" + "strings" + "time" + + anthropic "github.com/anthropics/anthropic-sdk-go" + "github.com/flanksource/captain/pkg/adapters/presentation" + openai "github.com/openai/openai-go" + "github.com/openai/openai-go/responses" + "google.golang.org/genai" +) + +type sdkSchemas struct { + prefix string + definitions map[string]any + sources map[string]sdkSource +} + +func enrichAPISchemas() { + for _, provider := range []struct { + name, version, docs string + request reflect.Type + extras map[string]reflect.Type + }{ + {"anthropic", "github.com/anthropics/anthropic-sdk-go v1.26.0", "https://platform.claude.com/docs/en/api/messages", reflect.TypeFor[anthropic.MessageNewParams](), nil}, + {"openai", "github.com/openai/openai-go v1.12.0", "https://platform.openai.com/docs/api-reference/responses/create", reflect.TypeFor[responses.ResponseNewParams](), nil}, + {"google", "google.golang.org/genai v1.57.0", "https://ai.google.dev/api/generate-content", reflect.TypeFor[genai.GenerateContentConfig](), map[string]reflect.Type{"contents": reflect.TypeFor[[]*genai.Content]()}}, + {"deepseek", "github.com/openai/openai-go v1.12.0", "https://api-docs.deepseek.com/api/create-chat-completion/", reflect.TypeFor[openai.ChatCompletionNewParams](), nil}, + } { + path := "pkg/adapters/" + provider.name + "/api.schema.json" + schema := readObject(path) + builder := &sdkSchemas{prefix: strings.ToUpper(provider.name[:1]) + provider.name[1:] + "API", definitions: map[string]any{}, sources: map[string]sdkSource{}} + native := builder.structure(provider.request) + properties := schema["properties"].(map[string]any) + for key, raw := range native["properties"].(map[string]any) { + field, exists := properties[key].(map[string]any) + if !exists { + field = map[string]any{"readOnly": true, "x-clicky-section": "environment", + "x-captain-option": map[string]any{"nativeName": key, "support": "unsupported", + "note": "Declared by " + provider.version + "; Captain does not construct this request option."}} + properties[key] = field + } + shape := raw.(map[string]any) + if provider.name == "anthropic" && key == "model" { + delete(field, "enum") + delete(field, "x-enum-labels") + delete(field, "x-enum-display") + } + for _, keyword := range []string{"type", "items", "properties", "additionalProperties", "oneOf", "anyOf", "$ref", "goJSONSchema"} { + delete(field, keyword) + } + for keyword, value := range shape { + if keyword != "title" && keyword != "description" { + field[keyword] = value + } + } + } + for key, kind := range provider.extras { + field := properties[key].(map[string]any) + shape := builder.value(kind) + for keyword, value := range shape { + field[keyword] = value + } + } + schema["$defs"] = builder.definitions + schema["x-captain-inventory"] = map[string]any{"sourceType": provider.request.String(), "version": provider.version} + presentation.AnnotateSchema(schema, provider.docs) + markNativeUnions(schema) + writeObject(path, schema) + fmt.Printf("%s: %d native request definitions from %s\n", provider.name, len(builder.definitions), provider.version) + } +} + +func (b *sdkSchemas) value(kind reflect.Type) map[string]any { + for kind.Kind() == reflect.Pointer { + kind = kind.Elem() + } + if kind == reflect.TypeFor[json.RawMessage]() || kind.Kind() == reflect.Interface { + return map[string]any{"format": "json"} + } + if kind == reflect.TypeFor[time.Time]() { + return map[string]any{"type": "string", "format": "date-time"} + } + if strings.Contains(kind.PkgPath(), "/param") && strings.HasPrefix(kind.Name(), "Opt[") { + field, exists := kind.FieldByName("Value") + if !exists { + panic("native optional type has no Value: " + kind.String()) + } + return b.value(field.Type) + } + if strings.HasSuffix(kind.PkgPath(), "/constant") { + raw, err := json.Marshal(reflect.Zero(kind).Interface()) + must(err) + var value any + must(json.Unmarshal(raw, &value)) + return map[string]any{"const": value} + } + if kind.Kind() == reflect.Struct && kind.Name() != "" { + name := b.prefix + kind.Name() + if _, exists := b.definitions[name]; !exists { + b.definitions[name] = map[string]any{} + b.definitions[name] = b.structure(kind) + } + return map[string]any{"$ref": "#/$defs/" + name} + } + switch kind.Kind() { + case reflect.String: + values := b.source(kind.PkgPath()).enums[kind.Name()] + if kind == reflect.TypeFor[anthropic.Model]() { + return map[string]any{"type": "string", "examples": values} + } + if len(values) > 0 { + return map[string]any{"type": "string", "enum": values} + } + return map[string]any{"type": "string"} + case reflect.Bool: + return map[string]any{"type": "boolean"} + case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64, reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64: + return map[string]any{"type": "integer"} + case reflect.Float32, reflect.Float64: + return map[string]any{"type": "number"} + case reflect.Slice, reflect.Array: + if kind.Elem().Kind() == reflect.Uint8 { + return map[string]any{"type": "string", "contentEncoding": "base64"} + } + return map[string]any{"type": "array", "items": b.value(kind.Elem())} + case reflect.Map: + if kind.Key().Kind() != reflect.String { + panic("non-string native map key: " + kind.String()) + } + return map[string]any{"type": "object", "additionalProperties": b.value(kind.Elem())} + case reflect.Struct: + return b.structure(kind) + default: + panic("unrepresentable native request type: " + kind.String()) + } +} + +func (b *sdkSchemas) structure(kind reflect.Type) map[string]any { + properties := map[string]any{} + var required, alternatives []any + source := b.source(kind.PkgPath()) + for i := 0; i < kind.NumField(); i++ { + field := kind.Field(i) + if !field.IsExported() { + continue + } + tag := strings.Split(field.Tag.Get("json"), ",") + if tag[0] == "-" { + continue + } + if contains(tag, "inline") { + alternatives = append(alternatives, b.value(field.Type)) + continue + } + if tag[0] == "" { + panic("native field has no JSON name: " + kind.String() + "." + field.Name) + } + value := b.value(field.Type) + if description := source.fields[kind.Name()+"."+field.Name]; description != "" { + value["description"] = description + } + properties[tag[0]] = value + if contains(tag, "required") { + required = append(required, tag[0]) + } + } + if len(alternatives) > 0 { + if len(properties) > 0 { + panic("native union mixes inline variants and properties: " + kind.String()) + } + return map[string]any{"anyOf": alternatives} + } + result := map[string]any{"type": "object", "additionalProperties": false, "properties": properties} + if len(required) > 0 { + result["required"] = required + } + if description := source.types[kind.Name()]; description != "" { + result["description"] = description + } + return result +} + +func contains(values []string, value string) bool { + for _, candidate := range values { + if candidate == value { + return true + } + } + return false +} diff --git a/hack/adapterresources/sdk_source.go b/hack/adapterresources/sdk_source.go new file mode 100644 index 00000000..013b791f --- /dev/null +++ b/hack/adapterresources/sdk_source.go @@ -0,0 +1,81 @@ +package main + +import ( + "go/ast" + "go/parser" + "go/token" + "os" + "os/exec" + "path/filepath" + "strconv" + "strings" +) + +type sdkSource struct { + fields map[string]string + types map[string]string + enums map[string][]any +} + +func (b *sdkSchemas) source(path string) sdkSource { + if source, exists := b.sources[path]; exists { + return source + } + source := sdkSource{fields: map[string]string{}, types: map[string]string{}, enums: map[string][]any{}} + if path == "" { + return source + } + dir, err := exec.Command("go", "list", "-f", "{{.Dir}}", path).Output() + must(err) + files, err := os.ReadDir(strings.TrimSpace(string(dir))) + must(err) + for _, file := range files { + if !strings.HasSuffix(file.Name(), ".go") || strings.HasSuffix(file.Name(), "_test.go") { + continue + } + parsed, err := parser.ParseFile(token.NewFileSet(), filepath.Join(strings.TrimSpace(string(dir)), file.Name()), nil, parser.ParseComments) + must(err) + collectSDKDeclarations(parsed, source) + } + b.sources[path] = source + return source +} + +func collectSDKDeclarations(file *ast.File, source sdkSource) { + for _, declaration := range file.Decls { + group, ok := declaration.(*ast.GenDecl) + if !ok { + continue + } + currentType := "" + for _, raw := range group.Specs { + switch spec := raw.(type) { + case *ast.TypeSpec: + source.types[spec.Name.Name] = group.Doc.Text() + if structure, ok := spec.Type.(*ast.StructType); ok { + for _, field := range structure.Fields.List { + for _, name := range field.Names { + source.fields[spec.Name.Name+"."+name.Name] = field.Doc.Text() + } + } + } + case *ast.ValueSpec: + if group.Tok != token.CONST { + continue + } + if kind, ok := spec.Type.(*ast.Ident); ok { + currentType = kind.Name + } + for _, rawValue := range spec.Values { + literal, ok := rawValue.(*ast.BasicLit) + if !ok || literal.Kind != token.STRING || currentType == "" { + continue + } + value, err := strconv.Unquote(literal.Value) + must(err) + source.enums[currentType] = append(source.enums[currentType], value) + } + } + } + } +} diff --git a/pkg/adapters/arbitrary_json_ginkgo_test.go b/pkg/adapters/arbitrary_json_ginkgo_test.go new file mode 100644 index 00000000..a12185e3 --- /dev/null +++ b/pkg/adapters/arbitrary_json_ginkgo_test.go @@ -0,0 +1,35 @@ +package adapters + +import ( + "github.com/flanksource/captain/pkg/adapters/presentation" + "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = ginkgo.Describe("arbitrary native JSON presentation", func() { + ginkgo.It("removes string-list hints when native array items require enum or structured controls", func() { + for _, items := range []map[string]any{ + {"$ref": "#/$defs/Include"}, {"type": "string", "enum": []any{"read", "write"}}, + } { + schema := map[string]any{"type": "array", "items": items, "x-array-display": "list"} + presentation.AnnotateSchema(schema, "https://example.com/schema") + Expect(schema).NotTo(HaveKeyWithValue("x-array-display", "list")) + } + }) + + ginkgo.It("uses typed JSON editors for untyped values without constraining their native type", func() { + schema := map[string]any{"type": "object", "properties": map[string]any{ + "payload": map[string]any{}, + "options": map[string]any{"type": "object", "additionalProperties": true}, + "label": map[string]any{"type": "string"}, + }} + presentation.AnnotateSchema(schema, "https://example.com/schema") + properties := schema["properties"].(map[string]any) + payload := properties["payload"].(map[string]any) + Expect(payload).To(HaveKeyWithValue("format", "json")) + Expect(payload).NotTo(HaveKey("type")) + options := properties["options"].(map[string]any)["additionalProperties"] + Expect(options).To(HaveKeyWithValue("format", "json")) + Expect(properties["label"]).To(HaveKeyWithValue("type", "string")) + }) +}) diff --git a/pkg/adapters/backend_resources.go b/pkg/adapters/backend_resources.go new file mode 100644 index 00000000..cb2ed4f9 --- /dev/null +++ b/pkg/adapters/backend_resources.go @@ -0,0 +1,49 @@ +package adapters + +import ( + "encoding/json" + + "github.com/flanksource/captain/pkg/adapters/presentation" + "github.com/flanksource/captain/pkg/api" +) + +func backendResourceSchemas() ([]SchemaDocument, error) { + raw, err := schemaFiles.ReadFile("resources/captain-backends.json") + if err != nil { + return nil, err + } + var source map[string]any + if err := json.Unmarshal(raw, &source); err != nil { + return nil, err + } + hooks, err := api.SchemaJSON(struct { + Sidecar *api.Workflow `json:"sidecar,omitempty"` + Supervisor *api.Workflow `json:"supervisor,omitempty"` + }{}) + if err != nil { + return nil, err + } + var hookSchema map[string]any + if err := json.Unmarshal(hooks, &hookSchema); err != nil { + return nil, err + } + var documents []SchemaDocument + for _, name := range []string{"docker", "git-agent"} { + schema := source["$defs"].(map[string]any)[name].(map[string]any) + schema["$schema"] = source["$schema"] + if name == "git-agent" { + schema["properties"].(map[string]any)["hooks"] = hookSchema + if definitions, ok := hookSchema["$defs"]; ok { + schema["$defs"] = definitions + delete(hookSchema, "$defs") + } + } + presentation.AnnotateSchema(schema, "https://github.com/flanksource/captain/tree/main/pkg/sandbox/adapter") + document, err := resourceDocument("captain", name+"-backend", schema) + if err != nil { + return nil, err + } + documents = append(documents, document) + } + return documents, nil +} diff --git a/pkg/adapters/catalog.go b/pkg/adapters/catalog.go index 3223d461..5d42b849 100644 --- a/pkg/adapters/catalog.go +++ b/pkg/adapters/catalog.go @@ -8,19 +8,21 @@ import ( "github.com/flanksource/captain/pkg/api/registry" ) -//go:embed */*.schema.json +//go:embed */*.schema.json resources var schemaFiles embed.FS -// SchemaDocument is one native runtime contract exposed to schema viewers. +// SchemaDocument is one execution, configuration or resource contract. type SchemaDocument struct { + ID string `json:"id"` + Kind string `json:"kind"` Provider string `json:"provider"` - Mode string `json:"mode"` + Mode string `json:"mode,omitempty"` Title string `json:"title"` Description string `json:"description"` Schema json.RawMessage `json:"schema"` } -// Schemas returns every non-cmux native runtime schema in canonical registry order. +// Schemas returns non-cmux execution schemas followed by native and Captain resources. func Schemas() ([]SchemaDocument, error) { var documents []SchemaDocument for _, provider := range registry.Providers() { @@ -36,7 +38,11 @@ func Schemas() ([]SchemaDocument, error) { documents = append(documents, document) } } - return documents, nil + resources, err := resourceSchemas() + if err != nil { + return nil, err + } + return append(documents, resources...), nil } func readSchemaDocument(path string) (SchemaDocument, error) { @@ -59,6 +65,7 @@ func readSchemaDocument(path string) (SchemaDocument, error) { return SchemaDocument{}, fmt.Errorf("adapter schema %s has incomplete viewer metadata", path) } return SchemaDocument{ + ID: metadata.Adapter.Provider + "/" + metadata.Adapter.Mode, Kind: "execution", Provider: metadata.Adapter.Provider, Mode: metadata.Adapter.Mode, Title: metadata.Title, Description: metadata.Description, Schema: raw, }, nil diff --git a/pkg/adapters/generate.go b/pkg/adapters/generate.go index fc06bde8..6efa11bc 100644 --- a/pkg/adapters/generate.go +++ b/pkg/adapters/generate.go @@ -1,13 +1,14 @@ package adapters -//go:generate go tool go-jsonschema --only-models --struct-name-from-title --extra-imports --package adapters --tags json --output zz_generated_anthropic_api.go anthropic/api.schema.json -//go:generate go tool go-jsonschema --only-models --struct-name-from-title --extra-imports --package adapters --tags json --output zz_generated_anthropic_agent.go anthropic/agent.schema.json -//go:generate go tool go-jsonschema --only-models --struct-name-from-title --extra-imports --package adapters --tags json --output zz_generated_anthropic_cli.go anthropic/cli.schema.json -//go:generate go tool go-jsonschema --only-models --struct-name-from-title --extra-imports --package adapters --tags json --output zz_generated_openai_api.go openai/api.schema.json -//go:generate go tool go-jsonschema --only-models --struct-name-from-title --extra-imports --package adapters --tags json --output zz_generated_openai_agent.go openai/agent.schema.json -//go:generate go tool go-jsonschema --only-models --struct-name-from-title --extra-imports --package adapters --tags json --output zz_generated_openai_cli.go openai/cli.schema.json -//go:generate go tool go-jsonschema --only-models --struct-name-from-title --extra-imports --package adapters --tags json --output zz_generated_google_api.go google/api.schema.json -//go:generate go tool go-jsonschema --only-models --struct-name-from-title --extra-imports --package adapters --tags json --output zz_generated_google_cli.go google/cli.schema.json -//go:generate go tool go-jsonschema --only-models --struct-name-from-title --extra-imports --package adapters --tags json --output zz_generated_deepseek_api.go deepseek/api.schema.json -//go:generate go tool go-jsonschema --only-models --struct-name-from-title --extra-imports --package adapters --tags json --output zz_generated_jev_api.go jev/api.schema.json -//go:generate go tool go-jsonschema --only-models --struct-name-from-title --extra-imports --package adapters --tags json --output zz_generated_bash_api.go bash/api.schema.json +//go:generate go tool go-jsonschema --only-models --schema-root-type =AnthropicAPIOptions --extra-imports --package adapters --tags json --output zz_generated_anthropic_api.go anthropic/api.schema.json +//go:generate go tool go-jsonschema --only-models --schema-root-type =AnthropicAgentOptions --extra-imports --package adapters --tags json --output zz_generated_anthropic_agent.go anthropic/agent.schema.json +//go:generate go tool go-jsonschema --only-models --schema-root-type =AnthropicCLIOptions --extra-imports --package adapters --tags json --output zz_generated_anthropic_cli.go anthropic/cli.schema.json +//go:generate go tool go-jsonschema --only-models --schema-root-type =OpenAIAPIOptions --extra-imports --package adapters --tags json --output zz_generated_openai_api.go openai/api.schema.json +//go:generate go tool go-jsonschema --only-models --schema-root-type =OpenAIAgentOptions --extra-imports --package adapters --tags json --output zz_generated_openai_agent.go openai/agent.schema.json +//go:generate go tool go-jsonschema --only-models --schema-root-type =OpenAICLIOptions --extra-imports --package adapters --tags json --output zz_generated_openai_cli.go openai/cli.schema.json +//go:generate go tool go-jsonschema --only-models --schema-root-type =GoogleAPIOptions --extra-imports --package adapters --tags json --output zz_generated_google_api.go google/api.schema.json +//go:generate go tool go-jsonschema --only-models --schema-root-type =GoogleCLIOptions --extra-imports --package adapters --tags json --output zz_generated_google_cli.go google/cli.schema.json +//go:generate go tool go-jsonschema --only-models --schema-root-type =DeepSeekAPIOptions --extra-imports --package adapters --tags json --output zz_generated_deepseek_api.go deepseek/api.schema.json +//go:generate go tool go-jsonschema --only-models --schema-root-type =JevAPIOptions --extra-imports --package adapters --tags json --output zz_generated_jev_api.go jev/api.schema.json +//go:generate go tool go-jsonschema --only-models --schema-root-type =BashAPIOptions --extra-imports --package adapters --tags json --output zz_generated_bash_api.go bash/api.schema.json +//go:generate go run ../../hack/adapterdto diff --git a/pkg/adapters/nested_resources_ginkgo_test.go b/pkg/adapters/nested_resources_ginkgo_test.go new file mode 100644 index 00000000..983b2dd3 --- /dev/null +++ b/pkg/adapters/nested_resources_ginkgo_test.go @@ -0,0 +1,22 @@ +package adapters + +import ( + "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = ginkgo.Describe("native nested resources", func() { + ginkgo.It("describes native API messages and tools with referenced SDK definitions", func() { + for _, document := range loadAdapterSchemas() { + if document.path != "anthropic/api.schema.json" && document.path != "openai/api.schema.json" && document.path != "google/api.schema.json" { + continue + } + definitions := objectFieldOrEmpty(document.body, "$defs") + Expect(len(definitions)).To(BeNumerically(">", 10), document.path) + properties := objectField(document.body, "properties", document.path) + tools := objectField(properties, "tools", document.path) + Expect(tools).To(HaveKey("items"), document.path) + Expect(objectField(tools, "items", document.path)).To(HaveKey("$ref"), document.path) + } + }) +}) diff --git a/pkg/adapters/presentation/presentation.go b/pkg/adapters/presentation/presentation.go new file mode 100644 index 00000000..97f4d3d9 --- /dev/null +++ b/pkg/adapters/presentation/presentation.go @@ -0,0 +1,178 @@ +package presentation + +import ( + "fmt" + "sort" + "strings" + "unicode" +) + +// AnnotateSchema adds form presentation without changing validation keywords. +func AnnotateSchema(schema map[string]any, docs string) { + annotateNode(schema, "Configuration", docs) +} + +func annotateNode(node map[string]any, name, docs string) { + annotateArbitraryJSON(node) + if node["title"] == nil { + node["title"] = Title(name) + } + if node["description"] == nil && name != "Configuration" { + node["description"] = fmt.Sprintf("%s configuration. See the linked native reference for semantics and availability.", Title(name)) + } + if docs != "" && node["x-help"] == nil { + node["x-help"] = map[string]any{"links": []any{map[string]any{"label": "Documentation", "href": docs}}} + } + annotateEnum(node) + if properties, ok := node["properties"].(map[string]any); ok { + keys := sortedKeys(properties) + for i, key := range keys { + if child, ok := properties[key].(map[string]any); ok { + if child["x-clicky-order"] == nil { + child["x-clicky-order"] = (i + 1) * 10 + } + annotateNode(child, key, docs) + } + } + } + for _, keyword := range []string{"$defs", "definitions", "patternProperties"} { + if children, ok := node[keyword].(map[string]any); ok { + for _, key := range sortedKeys(children) { + if child, ok := children[key].(map[string]any); ok { + annotateNode(child, key, docs) + } + } + } + } + for _, keyword := range []string{"items", "additionalProperties", "propertyNames", "if", "then", "else", "not"} { + if child, ok := node[keyword].(map[string]any); ok { + annotateNode(child, name+" value", docs) + } + } + for _, keyword := range []string{"oneOf", "anyOf", "allOf", "prefixItems"} { + if children, ok := node[keyword].([]any); ok { + for _, raw := range children { + if child, ok := raw.(map[string]any); ok { + annotateNode(child, name, docs) + } + } + } + } + if node["type"] == "array" { + items, _ := node["items"].(map[string]any) + plainString := items["type"] == "string" + for _, keyword := range []string{"$ref", "enum", "const", "oneOf", "anyOf", "allOf", "properties", "items", "additionalProperties"} { + if items[keyword] != nil { + plainString = false + } + } + if !plainString && node["x-array-display"] == "list" { + delete(node, "x-array-display") + } + if plainString && node["x-array-display"] == nil { + node["x-array-display"] = "list" + } + } +} + +func annotateArbitraryJSON(node map[string]any) { + if node["type"] == "object" { + _, properties := node["properties"] + if node["additionalProperties"] == true || (!properties && node["additionalProperties"] == nil) { + node["additionalProperties"] = map[string]any{"format": "json"} + } + return + } + if node["format"] != nil { + return + } + for _, keyword := range []string{"type", "$ref", "enum", "const", "properties", "additionalProperties", "patternProperties", "items", "anyOf", "oneOf", "allOf", "not", "if", "required"} { + if _, exists := node[keyword]; exists { + return + } + } + node["format"] = "json" +} + +func annotateEnum(node map[string]any) { + values, ok := node["enum"].([]any) + if !ok || len(values) == 0 { + return + } + labels := map[string]any{} + existing, _ := node["x-enum-labels"].(map[string]any) + icons := map[string]any{} + for _, raw := range values { + value, ok := raw.(string) + if !ok { + return + } + labels[value] = Title(value) + if value == "" { + labels[value] = "Default" + } + if label, ok := existing[value].(string); ok && label != "" { + labels[value] = label + } + if icon, ok := enumIcons[value]; ok { + icons[value] = icon + } + } + node["x-enum-labels"] = labels + if node["x-enum-display"] == nil { + node["x-enum-display"] = "combobox" + if len(values) <= 4 { + node["x-enum-display"] = "segmented" + } + } + if len(icons) == len(values) && node["x-enum-icons"] == nil { + node["x-enum-icons"] = icons + } +} + +var enumIcons = map[string]string{ + "": "shield", + "read-only": "lock", "read": "lock", "workspace-write": "folder", "write": "folder", + "danger-full-access": "lock-open", "full": "lock-open", "deny": "prohibit", "allow": "check", + "ask": "question", "auto": "sparkles", "default": "shield", "plan": "list-dashes", + "acceptEdits": "folder", "bypassPermissions": "lock-open", "dontAsk": "prohibit", + "enabled": "check", "disabled": "prohibit", "restricted": "shield", "unrestricted": "globe", + "off": "prohibit", "native": "shield", "docker": "package", "git-agent": "git-branch", +} + +// Title turns a native property name into a form label. +func Title(value string) string { + var out []rune + var previous rune + for _, r := range value { + if r == '_' || r == '-' { + out = append(out, ' ') + previous = r + continue + } + if unicode.IsUpper(r) && unicode.IsLower(previous) { + out = append(out, ' ') + } + if len(out) == 0 { + r = unicode.ToUpper(r) + } + out = append(out, r) + previous = r + } + words := strings.Fields(string(out)) + for index, word := range words { + if replacement, ok := map[string]string{"openai": "OpenAI", "deepseek": "DeepSeek", "mcp": "MCP", "api": "API", "cli": "CLI", "http": "HTTP", "https": "HTTPS", "json": "JSON", "yaml": "YAML", "toml": "TOML", "sdk": "SDK"}[strings.ToLower(word)]; ok { + words[index] = replacement + } + } + return strings.Join(words, " ") +} + +func sortedKeys(values map[string]any) []string { + keys := make([]string, 0, len(values)) + for key := range values { + keys = append(keys, key) + } + sort.Strings(keys) + return keys +} diff --git a/pkg/adapters/resource_annotations_ginkgo_test.go b/pkg/adapters/resource_annotations_ginkgo_test.go new file mode 100644 index 00000000..6cee940a --- /dev/null +++ b/pkg/adapters/resource_annotations_ginkgo_test.go @@ -0,0 +1,78 @@ +package adapters + +import ( + "encoding/json" + "fmt" + "net/url" + + "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = ginkgo.Describe("resource schema presentation", func() { + ginkgo.It("annotates nested properties, definitions, maps, arrays and union branches", func() { + documents, err := Schemas() + Expect(err).NotTo(HaveOccurred()) + for _, document := range documents { + var root map[string]any + Expect(json.Unmarshal(document.Schema, &root)).To(Succeed()) + walkPresentation(root, document.ID) + } + }) + + ginkgo.It("accounts for every captured CLI flag and alias", func() { + for _, document := range loadAdapterSchemas() { + if document.body["x-captain-inventory"] == nil || stringField(objectField(document.body, "x-captain-adapter", document.path), "mode") != "cli" { + continue + } + mapped := map[string]bool{} + for _, raw := range objectField(document.body, "properties", document.path) { + option := objectField(raw.(map[string]any), "x-captain-option", document.path) + mapped[stringField(option, "nativeName")] = true + if aliases, ok := option["aliases"].([]any); ok { + for _, alias := range aliases { + mapped[alias.(string)] = true + } + } + } + flags := objectField(document.body, "x-captain-inventory", document.path)["flags"].([]any) + Expect(len(flags)).To(BeNumerically(">", 10), document.path) + for _, flag := range flags { + Expect(mapped).To(HaveKeyWithValue(flag, true), document.path) + } + } + }) +}) + +func walkPresentation(node map[string]any, path string) { + Expect(node["title"]).To(BeAssignableToTypeOf(""), path) + links := objectField(node, "x-help", path)["links"].([]any) + Expect(links).NotTo(BeEmpty(), path) + for _, raw := range links { + href, err := url.Parse(stringField(raw.(map[string]any), "href")) + Expect(err).NotTo(HaveOccurred(), path) + Expect(href.Scheme).To(BeElementOf("https", "http"), path) + Expect(href.Host).NotTo(BeEmpty(), path) + } + for _, keyword := range []string{"properties", "$defs", "definitions", "patternProperties"} { + for key, raw := range objectFieldOrEmpty(node, keyword) { + if child, ok := raw.(map[string]any); ok { + walkPresentation(child, path+"/"+keyword+"/"+key) + } + } + } + for _, keyword := range []string{"items", "additionalProperties", "propertyNames", "if", "then", "else", "not"} { + if child, ok := node[keyword].(map[string]any); ok { + walkPresentation(child, path+"/"+keyword) + } + } + for _, keyword := range []string{"oneOf", "anyOf", "allOf", "prefixItems"} { + if children, ok := node[keyword].([]any); ok { + for index, raw := range children { + if child, ok := raw.(map[string]any); ok { + walkPresentation(child, fmt.Sprintf("%s/%s/%d", path, keyword, index)) + } + } + } + } +} diff --git a/pkg/adapters/resource_catalog.go b/pkg/adapters/resource_catalog.go new file mode 100644 index 00000000..1e32746b --- /dev/null +++ b/pkg/adapters/resource_catalog.go @@ -0,0 +1,163 @@ +package adapters + +import ( + "encoding/json" + "fmt" + "strings" + + "github.com/flanksource/captain/pkg/adapters/presentation" + "github.com/flanksource/captain/pkg/api" +) + +type resourceProjection struct { + provider string + name string + pointer string +} + +var resourceProjections = []resourceProjection{ + {"openai", "config", ""}, + {"openai", "permission-profile", "/definitions/PermissionProfileToml"}, + {"openai", "filesystem", "/definitions/FilesystemPermissionsToml"}, + {"openai", "network", "/definitions/NetworkToml"}, + {"openai", "sandbox", "/definitions/SandboxWorkspaceWrite"}, + {"openai", "mcp-server", "/definitions/RawMcpServerConfig"}, + {"openai", "hooks", "/definitions/HooksToml"}, + {"openai", "agent-definition", "/definitions/AgentRoleToml"}, + {"openai", "profile", "/definitions/ConfigProfile"}, + {"anthropic", "settings", ""}, + {"anthropic", "sandbox", "/definitions/Settings/properties/sandbox"}, + {"anthropic", "permissions", "/definitions/Settings/properties/permissions"}, + {"anthropic", "hooks", "/definitions/Settings/properties/hooks"}, + {"anthropic", "skills", "/definitions/Settings/properties/skillOverrides"}, + {"anthropic", "plugins", "/definitions/Settings/properties/enabledPlugins"}, + {"anthropic", "mcp-server", "/definitions/McpServerConfigForProcessTransport"}, + {"anthropic", "agent-definition", "/definitions/AgentDefinition"}, + {"anthropic", "plugin", "/definitions/SdkPluginConfig"}, + {"google", "settings", ""}, + {"google", "sandbox", "/properties/tools/properties/sandbox"}, + {"google", "permissions", "/properties/security"}, + {"google", "mcp-servers", "/properties/mcpServers"}, + {"google", "hooks", "/properties/hooks"}, + {"google", "agents", "/properties/agents"}, + {"google", "skills", "/properties/skills"}, + {"google", "extensions", "/properties/extensions"}, + {"google", "model", "/properties/model"}, + {"google", "context", "/properties/context"}, + {"google", "environment", "/properties/advanced"}, +} + +func resourceSchemas() ([]SchemaDocument, error) { + sources := map[string]map[string]any{} + for _, provider := range []string{"openai", "anthropic", "google"} { + raw, err := schemaFiles.ReadFile("resources/" + provider + ".json") + if err != nil { + return nil, fmt.Errorf("read %s resource schema: %w", provider, err) + } + var schema map[string]any + if err := json.Unmarshal(raw, &schema); err != nil { + return nil, fmt.Errorf("decode %s resources: %w", provider, err) + } + sources[provider] = schema + } + var documents []SchemaDocument + for _, projection := range resourceProjections { + document, err := projectResource(sources[projection.provider], projection) + if err != nil { + return nil, err + } + documents = append(documents, document) + } + portable, err := captainResourceSchemas() + if err != nil { + return nil, err + } + documents = append(documents, portable...) + backends, err := backendResourceSchemas() + return append(documents, backends...), err +} + +func projectResource(source map[string]any, projection resourceProjection) (SchemaDocument, error) { + selected, err := schemaPointer(source, projection.pointer) + if err != nil { + return SchemaDocument{}, fmt.Errorf("resource %s/%s: %w", projection.provider, projection.name, err) + } + schema := map[string]any{} + for key, value := range selected { + schema[key] = value + } + for _, key := range []string{"$schema", "definitions", "$defs", "x-captain-resource"} { + if value, ok := source[key]; ok { + schema[key] = value + } + } + schema["title"] = presentation.Title(projection.provider) + " " + presentation.Title(projection.name) + if schema["description"] == nil { + schema["description"] = fmt.Sprintf("Native %s %s configuration.", projection.provider, projection.name) + } + return resourceDocument(projection.provider, projection.name, schema) +} + +func schemaPointer(root map[string]any, pointer string) (map[string]any, error) { + node := root + for _, key := range strings.Split(strings.TrimPrefix(pointer, "/"), "/") { + if pointer == "" { + break + } + key = strings.ReplaceAll(strings.ReplaceAll(key, "~1", "/"), "~0", "~") + child, ok := node[key].(map[string]any) + if !ok { + return nil, fmt.Errorf("schema pointer %q has no object at %q", pointer, key) + } + node = child + } + return node, nil +} + +func resourceDocument(provider, name string, schema map[string]any) (SchemaDocument, error) { + pruneDefinitions(schema) + raw, err := json.Marshal(schema) + if err != nil { + return SchemaDocument{}, fmt.Errorf("encode resource %s/%s: %w", provider, name, err) + } + kind := "resource" + if name == "config" || name == "settings" { + kind = "configuration" + } + title, _ := schema["title"].(string) + description, _ := schema["description"].(string) + return SchemaDocument{ID: provider + "/" + name, Kind: kind, Provider: provider, + Title: title, Description: description, Schema: raw}, nil +} + +func captainResourceSchemas() ([]SchemaDocument, error) { + resources := []struct { + name string + value any + }{ + {"sandbox", api.SandboxRef{}}, {"sandbox-policy", api.NativeSandboxPolicy{}}, + {"permissions", api.Permissions{}}, {"preset", api.RuntimePreset{}}, + {"spec", api.Spec{}}, {"tools", api.Tools{}}, {"mcp", api.MCP{}}, + {"resource-policy", api.ResourcePolicies{}}, {"dispatch", api.SandboxDispatchPolicy{}}, + } + var documents []SchemaDocument + for _, resource := range resources { + raw, err := api.SchemaJSON(resource.value) + if err != nil { + return nil, err + } + var schema map[string]any + if err := json.Unmarshal(raw, &schema); err != nil { + return nil, err + } + schema["title"] = "Captain " + presentation.Title(resource.name) + schema["description"] = "Portable Captain " + presentation.Title(resource.name) + " configuration. Runtime capabilities determine which settings can be enforced." + presentation.AnnotateSchema(schema, "https://github.com/flanksource/captain") + document, err := resourceDocument("captain", resource.name, schema) + if err != nil { + return nil, err + } + documents = append(documents, document) + } + return documents, nil +} diff --git a/pkg/adapters/resource_references.go b/pkg/adapters/resource_references.go new file mode 100644 index 00000000..bd7d693c --- /dev/null +++ b/pkg/adapters/resource_references.go @@ -0,0 +1,44 @@ +package adapters + +import "strings" + +func pruneDefinitions(schema map[string]any) { + for _, keyword := range []string{"definitions", "$defs"} { + definitions, ok := schema[keyword].(map[string]any) + if !ok { + continue + } + used := map[string]any{} + var walk func(any) + walk = func(raw any) { + switch node := raw.(type) { + case map[string]any: + if ref, ok := node["$ref"].(string); ok && strings.HasPrefix(ref, "#/"+keyword+"/") { + key := strings.SplitN(strings.TrimPrefix(ref, "#/"+keyword+"/"), "/", 2)[0] + key = strings.ReplaceAll(strings.ReplaceAll(key, "~1", "/"), "~0", "~") + if _, exists := used[key]; !exists { + if definition, exists := definitions[key]; exists { + used[key] = definition + walk(definition) + } + } + } + for key, value := range node { + if key != "definitions" && key != "$defs" { + walk(value) + } + } + case []any: + for _, value := range node { + walk(value) + } + } + } + walk(schema) + if len(used) == 0 { + delete(schema, keyword) + } else { + schema[keyword] = used + } + } +} diff --git a/pkg/adapters/resources/README.md b/pkg/adapters/resources/README.md new file mode 100644 index 00000000..de497378 --- /dev/null +++ b/pkg/adapters/resources/README.md @@ -0,0 +1,3 @@ +# Native resource schema snapshots + +These snapshots come from versioned upstream configuration schemas and Captain's pinned Claude Agent SDK declarations. `go run ./hack/adapterresources` imports captured sources from `.tmp/adapter-schema-sources`; see the [adapter resource guide](../../../docs/adapter-resource-schemas.md) for capture commands. The catalog exposes reusable resource projections without copying their definitions. diff --git a/pkg/adapters/resources/captain-backends.json b/pkg/adapters/resources/captain-backends.json new file mode 100644 index 00000000..a5bfbde1 --- /dev/null +++ b/pkg/adapters/resources/captain-backends.json @@ -0,0 +1,50 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$defs": { + "docker": { + "type": "object", + "title": "Docker backend", + "description": "Trusted Docker backend entry in ~/.captain.yaml under sandbox.backends.. An image may instead come from the project's .container-sandbox.yaml. Host mounts and environment access are grants made by the machine owner.", + "additionalProperties": false, + "required": ["kind"], + "x-captain-source": "pkg/sandbox/adapter/container.go", + "properties": { + "kind": { "type": "string", "const": "docker", "default": "docker" }, + "image": { "type": "string", "description": "Container image override. Required at execution when no project image is configured." }, + "presets": { "type": "array", "items": { "type": "string" }, "description": "Named dependency presets that grant host cache mounts and credential environment passthrough." }, + "env": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Environment variables expanded from the trusted machine environment and passed into Docker." }, + "envPassthrough": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Names of existing host environment variables to pass into the container." }, + "volumes": { "type": "array", "items": { "type": "string", "pattern": "^[^:]+:[^:]+(?::ro)?$" }, "description": "Trusted host mounts as source:target[:ro]. Project configuration uses structured volume objects instead." } + } + }, + "git-agent": { + "type": "object", + "title": "Git Agent backend", + "description": "Trusted Git Agent backend entry in ~/.captain.yaml under sandbox.backends.. Enrollment records are managed by captain sandbox git-agent add. This preview does not read credential files or contact agents.", + "additionalProperties": false, + "required": ["kind"], + "x-captain-source": "pkg/sandbox/adapter/gitagent.go", + "properties": { + "kind": { "type": "string", "const": "git-agent", "default": "git-agent" }, + "relay": { "type": "string", "enum": ["sync", "async"], "default": "sync", "description": "Mailbox relay behavior for dispatched tasks." }, + "key": { "type": "string", "description": "Path to the supervisor's dispatch SSH key. Defaults beside the Captain configuration." }, + "mailboxRoot": { "type": "string", "description": "Root served by the long-running mailbox endpoint." }, + "waitTimeout": { "type": "string", "pattern": "^(?:[0-9]+(?:\\.[0-9]+)?(?:ns|us|µs|μs|ms|s|m|h))+$", "description": "Positive Go duration for waiting for a terminal verdict, for example 1h or 30m. Runtime validation also rejects zero durations.", "default": "1h" }, + "agents": { + "type": "object", "readOnly": true, + "description": "Enrollment-managed endpoints and paths. Re-enroll an agent to update transport trust and credentials.", + "additionalProperties": { + "type": "object", "additionalProperties": false, "required": ["url"], + "properties": { + "url": { "type": "string", "pattern": "^(ssh|https)://", "description": "Enrolled agent endpoint." }, + "hostFingerprint": { "type": "string", "description": "Pinned SSH host key fingerprint." }, + "tokenPath": { "type": "string", "description": "Path to the HTTPS dispatch token, never its contents." }, + "caPath": { "type": "string", "description": "Path to the trusted HTTPS certificate authority." }, + "pinnedPubkey": { "type": "string", "description": "Pinned HTTPS server public key." } + } + } + } + } + } + } +} diff --git a/pkg/adapters/resources_contract_ginkgo_test.go b/pkg/adapters/resources_contract_ginkgo_test.go new file mode 100644 index 00000000..be9cd4a7 --- /dev/null +++ b/pkg/adapters/resources_contract_ginkgo_test.go @@ -0,0 +1,95 @@ +package adapters + +import ( + "bytes" + "encoding/json" + + "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" + jsonschema "github.com/santhosh-tekuri/jsonschema/v6" +) + +var _ = ginkgo.Describe("resource schema catalog", func() { + ginkgo.It("includes native configuration, permission profiles and portable Captain resources", func() { + documents, err := Schemas() + Expect(err).NotTo(HaveOccurred()) + raw, err := json.Marshal(documents) + Expect(err).NotTo(HaveOccurred()) + var catalog []map[string]any + Expect(json.Unmarshal(raw, &catalog)).To(Succeed()) + ids := make([]any, 0, len(catalog)) + for _, document := range catalog { + ids = append(ids, document["id"]) + } + Expect(ids).To(ContainElements( + "openai/config", "openai/permission-profile", "anthropic/settings", "anthropic/sandbox", + "google/settings", "captain/sandbox", "captain/permissions", "captain/preset", + )) + Expect(ids).To(HaveEach(Not(BeNil()))) + Expect(ids).To(ConsistOf(uniqueResourceIDs(ids))) + }) + + ginkgo.It("compiles every catalog document with self-contained references", func() { + documents, err := Schemas() + Expect(err).NotTo(HaveOccurred()) + for _, document := range documents { + body, err := jsonschema.UnmarshalJSON(bytes.NewReader(document.Schema)) + Expect(err).NotTo(HaveOccurred(), document.Title) + compiler := jsonschema.NewCompiler() + Expect(compiler.AddResource("mem:///resource.json", body)).To(Succeed()) + _, err = compiler.Compile("mem:///resource.json") + Expect(err).NotTo(HaveOccurred(), document.Title) + } + }) + + ginkgo.It("reports the failing type through referenced permission definitions", func() { + value, err := jsonschema.UnmarshalJSON(bytes.NewBufferString(`{"workspace_roots":{"/workspace":"yes"}}`)) + Expect(err).NotTo(HaveOccurred()) + result, err := ValidateResource("openai/permission-profile", value) + Expect(err).NotTo(HaveOccurred()) + Expect(result.Errors).To(HaveLen(1)) + Expect(result.Errors[0].InstancePath).To(Equal("/workspace_roots/~1workspace")) + Expect(result.Errors[0].Message).To(ContainSubstring("boolean")) + }) + + ginkgo.It("rejects invalid nested sandbox values and preserves named profile references", func() { + for _, example := range []struct { + id string + value string + valid bool + }{ + {"captain/sandbox", `{"mode":"native","policy":{"network":{"httpProxyPort":70000}}}`, false}, + {"captain/permissions", `{"mode":"plan","tools":{"Bash":"deny"}}`, true}, + {"captain/permissions", `{"tools":{"Bash":"unknown"}}`, false}, + {"openai/permission-profile", `{"extends":"team-workspace","workspace_roots":{"/workspace":true}}`, true}, + {"openai/permission-profile", `{"network":{"enabled":"yes"}}`, false}, + {"openai/permission-profile", `{"workspace_roots":{"/workspace":"yes"}}`, false}, + {"openai/filesystem", `{"/workspace":"write","/private":"deny"}`, true}, + {"openai/filesystem", `{"/workspace":"execute"}`, false}, + {"captain/docker-backend", `{"kind":"docker","env":{"EXAMPLE":42}}`, false}, + {"captain/git-agent-backend", `{"kind":"git-agent","relay":"invalid"}`, false}, + {"anthropic/sandbox", `{"network":{"allowedDomains":["example.com"]}}`, true}, + {"anthropic/sandbox", `{"network":{"allowedDomains":42}}`, false}, + {"anthropic/api", `{"model":"claude-sonnet-5","max_tokens":128,"messages":[{"role":"user","content":[{"type":"text","text":"Inspect the example"}]}]}`, true}, + {"anthropic/api", `{"model":"claude-sonnet-5","max_tokens":128,"messages":[{"role":"user","content":[{"type":"text","text":42}]}]}`, false}, + } { + value, err := jsonschema.UnmarshalJSON(bytes.NewBufferString(example.value)) + Expect(err).NotTo(HaveOccurred()) + result, err := ValidateResource(example.id, value) + Expect(err).NotTo(HaveOccurred(), example.id) + Expect(result.Valid).To(Equal(example.valid), "%s: %v", example.id, result.Errors) + } + }) +}) + +func uniqueResourceIDs(ids []any) []any { + seen := map[any]bool{} + var unique []any + for _, id := range ids { + if !seen[id] { + unique = append(unique, id) + seen[id] = true + } + } + return unique +} diff --git a/pkg/adapters/schema_contract_ginkgo_test.go b/pkg/adapters/schema_contract_ginkgo_test.go index 97c8aee2..cec0ece3 100644 --- a/pkg/adapters/schema_contract_ginkgo_test.go +++ b/pkg/adapters/schema_contract_ginkgo_test.go @@ -60,10 +60,11 @@ var _ = ginkgo.Describe("Adapter schema contract", func() { ginkgo.It("embeds every schema for runtime viewers in canonical order", func() { documents, err := Schemas() Expect(err).NotTo(HaveOccurred()) - Expect(documents).To(HaveLen(len(expectedSchemaPaths()))) - actual := make([]string, 0, len(documents)) for _, document := range documents { + if document.Kind != "execution" { + continue + } path := filepath.Join(document.Provider, document.Mode+".schema.json") actual = append(actual, path) raw, err := os.ReadFile(path) @@ -105,7 +106,7 @@ var _ = ginkgo.Describe("Adapter schema contract", func() { }) ginkgo.It("round trips native JSON names through every generated root DTO", func() { - assertJSONRoundTrip[AnthropicAPIOptions](map[string]any{"model": "claude-sonnet-5", "max_tokens": 2048, "messages": []any{map[string]any{"role": "user"}}, "stream": true, "metadata": map[string]any{"user_id": "tenant-x"}}) + assertJSONRoundTrip[AnthropicAPIOptions](map[string]any{"model": "claude-sonnet-5", "max_tokens": 2048, "messages": []any{map[string]any{"role": "user", "content": []any{map[string]any{"type": "text", "text": "Inspect the example"}}}}, "stream": true, "metadata": map[string]any{"user_id": "tenant-x"}}) assertJSONRoundTrip[AnthropicAgentOptions](map[string]any{"model": "claude-sonnet-5", "includePartialMessages": true, "agent": "reviewer"}) assertJSONRoundTrip[AnthropicCLIOptions](map[string]any{"model": "claude-sonnet-5", "print": true, "agent": "reviewer"}) assertJSONRoundTrip[OpenAIAPIOptions](map[string]any{"model": "gpt-5.6", "input": "hello", "stream": true, "background": true}) @@ -161,9 +162,9 @@ var _ = ginkgo.Describe("Adapter schema contract", func() { ginkgo.It("generates named permission profiles as strings", func() { for _, field := range []reflect.StructField{ - generatedField(reflect.TypeFor[ThreadStart](), "Permissions"), - generatedField(reflect.TypeFor[ThreadResume](), "Permissions"), - generatedField(reflect.TypeFor[TurnStart](), "Permissions"), + generatedField(reflect.TypeFor[OpenAIAgentOptionsThreadStart](), "Permissions"), + generatedField(reflect.TypeFor[OpenAIAgentOptionsThreadResume](), "Permissions"), + generatedField(reflect.TypeFor[OpenAIAgentOptionsTurnStart](), "Permissions"), } { Expect(field.Type.Kind()).To(Equal(reflect.Pointer), field.Name) Expect(field.Type.Elem().Kind()).To(Equal(reflect.String), field.Name) @@ -247,7 +248,7 @@ func walkLeafOptions(schema map[string]any, prefix string, visit func(string, ma field, ok := properties[name].(map[string]any) Expect(ok).To(BeTrue(), "%s/%s must be an object", prefix, name) path := prefix + "/" + name - if len(objectFieldOrEmpty(field, "properties")) > 0 { + if field["x-captain-option"] == nil && len(objectFieldOrEmpty(field, "properties")) > 0 { walkLeafOptions(field, path, visit) continue } diff --git a/pkg/adapters/validation.go b/pkg/adapters/validation.go new file mode 100644 index 00000000..878d7ce2 --- /dev/null +++ b/pkg/adapters/validation.go @@ -0,0 +1,85 @@ +package adapters + +import ( + "bytes" + "errors" + "fmt" + "sync" + + jsonschema "github.com/santhosh-tekuri/jsonschema/v6" +) + +var ErrUnknownSchema = errors.New("unknown schema") + +type ValidationIssue struct { + InstancePath string `json:"instancePath"` + SchemaPath string `json:"schemaPath"` + Message string `json:"message"` +} + +type ValidationResult struct { + Valid bool `json:"valid"` + Errors []ValidationIssue `json:"errors"` +} + +var compiledResources = sync.OnceValues(func() (map[string]*jsonschema.Schema, error) { + documents, err := Schemas() + if err != nil { + return nil, err + } + compiled := make(map[string]*jsonschema.Schema, len(documents)) + for _, document := range documents { + body, err := jsonschema.UnmarshalJSON(bytes.NewReader(document.Schema)) + if err != nil { + return nil, fmt.Errorf("decode %s: %w", document.ID, err) + } + compiler := jsonschema.NewCompiler() + uri := "mem:///" + document.ID + ".json" + if err := compiler.AddResource(uri, body); err != nil { + return nil, fmt.Errorf("register %s: %w", document.ID, err) + } + schema, err := compiler.Compile(uri) + if err != nil { + return nil, fmt.Errorf("compile %s: %w", document.ID, err) + } + if _, exists := compiled[document.ID]; exists { + return nil, fmt.Errorf("duplicate resource id %q", document.ID) + } + compiled[document.ID] = schema + } + return compiled, nil +}) + +// ValidateResource checks a value against its published schema without resolving or executing it. +func ValidateResource(id string, value any) (ValidationResult, error) { + compiled, err := compiledResources() + if err != nil { + return ValidationResult{}, err + } + schema, exists := compiled[id] + if !exists { + return ValidationResult{}, fmt.Errorf("%w %q", ErrUnknownSchema, id) + } + result := ValidationResult{Valid: true, Errors: []ValidationIssue{}} + if err := schema.Validate(value); err != nil { + var invalid *jsonschema.ValidationError + if !errors.As(err, &invalid) { + return ValidationResult{}, fmt.Errorf("validate %s: %w", id, err) + } + result.Valid = false + result.Errors = validationIssues(*invalid.DetailedOutput()) + } + return result, nil +} + +func validationIssues(output jsonschema.OutputUnit) []ValidationIssue { + if len(output.Errors) == 0 && output.Error != nil { + return []ValidationIssue{{InstancePath: output.InstanceLocation, + SchemaPath: output.KeywordLocation, Message: output.Error.String()}} + } + var issues []ValidationIssue + for _, child := range output.Errors { + issues = append(issues, validationIssues(child)...) + } + return issues +} From b1807b99ea6a8dabd2a6b2f01dd1dfc4f55bdc26 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Fri, 23 Oct 2026 16:05:43 +0300 Subject: [PATCH 21/77] feat(cli): add adapter schema validation endpoint and resource preview UI Add POST /api/captain/ai/adapter-schemas/validate to check a preview value against an embedded schema without executing or saving it. The schema page gains form, JSON, and YAML views with local drafts, resource search, and provenance links. Catalog entries now include id and kind, and mode is optional for portable resources. BREAKING CHANGE: unknown provider/mode routes under /adapter-schemas now show an error instead of falling back to the first schema. Claude-Session-Id: b00416a9-facd-49f8-9bc6-cd4ef7eba6b4 --- .../serve_adapter_resources_ginkgo_test.go | 31 +++ pkg/cli/serve_adapter_schemas.go | 47 ++++ pkg/cli/serve_adapter_schemas_ginkgo_test.go | 4 + pkg/cli/serve_adapter_schemas_openapi.go | 26 ++ pkg/cli/serve_openapi.go | 6 +- pkg/cli/webapp/src/AdapterSchemaPreview.tsx | 56 +++++ .../webapp/src/AdapterSchemaProvenance.tsx | 30 +++ .../webapp/src/AdapterSchemasPage.test.tsx | 34 ++- pkg/cli/webapp/src/AdapterSchemasPage.tsx | 232 +++++++----------- pkg/cli/webapp/src/App.tsx | 1 + pkg/cli/webapp/src/adapterSchemaDraft.test.ts | 29 +++ pkg/cli/webapp/src/adapterSchemaDraft.ts | 23 ++ pkg/cli/webapp/src/adapterSchemas.test.ts | 7 +- pkg/cli/webapp/src/adapterSchemas.ts | 37 ++- pkg/cli/webapp/src/main.tsx | 4 + 15 files changed, 400 insertions(+), 167 deletions(-) create mode 100644 pkg/cli/serve_adapter_resources_ginkgo_test.go create mode 100644 pkg/cli/serve_adapter_schemas_openapi.go create mode 100644 pkg/cli/webapp/src/AdapterSchemaPreview.tsx create mode 100644 pkg/cli/webapp/src/AdapterSchemaProvenance.tsx create mode 100644 pkg/cli/webapp/src/adapterSchemaDraft.test.ts create mode 100644 pkg/cli/webapp/src/adapterSchemaDraft.ts diff --git a/pkg/cli/serve_adapter_resources_ginkgo_test.go b/pkg/cli/serve_adapter_resources_ginkgo_test.go new file mode 100644 index 00000000..8ab97f47 --- /dev/null +++ b/pkg/cli/serve_adapter_resources_ginkgo_test.go @@ -0,0 +1,31 @@ +package cli + +import ( + "net/http" + "net/http/httptest" + "strings" + + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("adapter resource validation", func() { + DescribeTable("validates values without applying configuration", func(body string, status int, expected string) { + mux := http.NewServeMux() + registerAdapterSchemaHandlers(mux) + response := httptest.NewRecorder() + mux.ServeHTTP(response, httptest.NewRequest(http.MethodPost, + "/api/captain/ai/adapter-schemas/validate", strings.NewReader(body))) + Expect(response.Code).To(Equal(status), response.Body.String()) + Expect(response.Body.String()).To(ContainSubstring(expected)) + }, + Entry("valid permissions", `{"id":"captain/permissions","value":{"mode":"plan"}}`, http.StatusOK, `"valid":true`), + Entry("invalid permissions", `{"id":"captain/permissions","value":{"mode":"unknown"}}`, http.StatusOK, `"valid":false`), + Entry("unknown resource", `{"id":"missing/config","value":{}}`, http.StatusNotFound, "unknown schema"), + Entry("missing value", `{"id":"captain/permissions"}`, http.StatusBadRequest, "value is required"), + Entry("missing identity", `{"value":{}}`, http.StatusBadRequest, "id is required"), + Entry("null value", `{"id":"captain/permissions","value":null}`, http.StatusOK, `"valid":false`), + Entry("unknown request field", `{"id":"captain/permissions","value":{},"apply":true}`, http.StatusBadRequest, "unknown field"), + Entry("trailing document", `{"id":"captain/permissions","value":{}} {}`, http.StatusBadRequest, "single JSON"), + ) +}) diff --git a/pkg/cli/serve_adapter_schemas.go b/pkg/cli/serve_adapter_schemas.go index e75c1f0f..34e5d854 100644 --- a/pkg/cli/serve_adapter_schemas.go +++ b/pkg/cli/serve_adapter_schemas.go @@ -1,13 +1,60 @@ package cli import ( + "bytes" + "encoding/json" + "errors" + "fmt" + "io" "net/http" "github.com/flanksource/captain/pkg/adapters" + jsonschema "github.com/santhosh-tekuri/jsonschema/v6" ) func registerAdapterSchemaHandlers(mux *http.ServeMux) { mux.HandleFunc("GET /api/captain/ai/adapter-schemas", handleAdapterSchemas()) + mux.HandleFunc("POST /api/captain/ai/adapter-schemas/validate", handleAdapterSchemaValidation) +} + +func handleAdapterSchemaValidation(w http.ResponseWriter, r *http.Request) { + var request struct { + ID string `json:"id"` + Value json.RawMessage `json:"value"` + } + decoder := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<20)) + decoder.DisallowUnknownFields() + if err := decoder.Decode(&request); err != nil { + http.Error(w, fmt.Sprintf("invalid validation request: %v", err), http.StatusBadRequest) + return + } + if err := decoder.Decode(new(any)); err != io.EOF { + http.Error(w, "validation request must contain a single JSON document", http.StatusBadRequest) + return + } + if request.ID == "" { + http.Error(w, "id is required", http.StatusBadRequest) + return + } + if len(request.Value) == 0 { + http.Error(w, "value is required", http.StatusBadRequest) + return + } + value, err := jsonschema.UnmarshalJSON(bytes.NewReader(request.Value)) + if err != nil { + http.Error(w, err.Error(), http.StatusBadRequest) + return + } + result, err := adapters.ValidateResource(request.ID, value) + if err != nil { + status := http.StatusInternalServerError + if errors.Is(err, adapters.ErrUnknownSchema) { + status = http.StatusNotFound + } + http.Error(w, err.Error(), status) + return + } + writeServeJSON(w, http.StatusOK, result) } func handleAdapterSchemas() http.HandlerFunc { diff --git a/pkg/cli/serve_adapter_schemas_ginkgo_test.go b/pkg/cli/serve_adapter_schemas_ginkgo_test.go index 7423979e..9608d4cb 100644 --- a/pkg/cli/serve_adapter_schemas_ginkgo_test.go +++ b/pkg/cli/serve_adapter_schemas_ginkgo_test.go @@ -39,5 +39,9 @@ var _ = Describe("adapter schema viewer API", func() { Expect(spec.Paths).To(HaveKey("/api/captain/ai/adapter-schemas")) operation := spec.Paths["/api/captain/ai/adapter-schemas"]["get"] Expect(operation.OperationID).To(Equal("listAdapterSchemas")) + Expect(spec.Paths).To(HaveKey("/api/captain/ai/adapter-schemas/validate")) + validation := spec.Paths["/api/captain/ai/adapter-schemas/validate"]["post"] + Expect(validation.RequestBody.Content["application/json"].Schema.Required).To(ConsistOf("id", "value")) + Expect(validation.Responses).To(HaveKey("404")) }) }) diff --git a/pkg/cli/serve_adapter_schemas_openapi.go b/pkg/cli/serve_adapter_schemas_openapi.go new file mode 100644 index 00000000..194d5e09 --- /dev/null +++ b/pkg/cli/serve_adapter_schemas_openapi.go @@ -0,0 +1,26 @@ +package cli + +import "github.com/flanksource/clicky/rpc" + +func addAdapterSchemaValidationPath(spec *rpc.OpenAPISpec) { + issue := &rpc.OpenAPISchema{Type: "object", Required: []string{"instancePath", "schemaPath", "message"}, + Properties: map[string]*rpc.OpenAPISchema{ + "instancePath": {Type: "string"}, "schemaPath": {Type: "string"}, "message": {Type: "string"}, + }} + spec.Paths["/api/captain/ai/adapter-schemas/validate"] = rpc.OpenAPIPath{"post": { + Tags: []string{"Adapter schemas"}, Summary: "Validate a local preview value without executing or saving it", OperationID: "validateAdapterSchema", + RequestBody: &rpc.OpenAPIRequestBody{Required: true, Content: map[string]rpc.OpenAPIMediaType{ + "application/json": {Schema: &rpc.OpenAPISchema{Type: "object", Required: []string{"id", "value"}, + Properties: map[string]*rpc.OpenAPISchema{"id": {Type: "string"}, "value": {}}, + }}, + }}, + Responses: map[string]rpc.OpenAPIResponse{ + "200": jsonResponse(&rpc.OpenAPISchema{Type: "object", Required: []string{"valid", "errors"}, + Properties: map[string]*rpc.OpenAPISchema{ + "valid": {Type: "boolean"}, "errors": {Type: "array", Items: issue}, + }}), + "400": {Description: "Malformed request, missing value or body larger than 1 MiB"}, + "404": {Description: "Unknown schema id"}, "500": {Description: "Embedded schema is invalid"}, + }, + }} +} diff --git a/pkg/cli/serve_openapi.go b/pkg/cli/serve_openapi.go index 53500a17..73b7317e 100644 --- a/pkg/cli/serve_openapi.go +++ b/pkg/cli/serve_openapi.go @@ -212,19 +212,21 @@ func addCaptainAdapterSchemaPaths(spec *rpc.OpenAPISpec) { spec.Paths = map[string]rpc.OpenAPIPath{} } document := &rpc.OpenAPISchema{ - Type: "object", Required: []string{"provider", "mode", "title", "description", "schema"}, + Type: "object", Required: []string{"id", "kind", "provider", "title", "description", "schema"}, Properties: map[string]*rpc.OpenAPISchema{ + "id": {Type: "string"}, "kind": {Type: "string", Enum: []any{"execution", "configuration", "resource"}}, "provider": {Type: "string"}, "mode": {Type: "string"}, "title": {Type: "string"}, "description": {Type: "string"}, "schema": {Type: "object"}, }, } spec.Paths["/api/captain/ai/adapter-schemas"] = rpc.OpenAPIPath{"get": { - Tags: []string{"Adapter schemas"}, Summary: "List native runtime adapter schemas", OperationID: "listAdapterSchemas", + Tags: []string{"Adapter schemas"}, Summary: "List native and portable resource schemas", OperationID: "listAdapterSchemas", Responses: map[string]rpc.OpenAPIResponse{ "200": jsonResponse(&rpc.OpenAPISchema{Type: "array", Items: document}), "500": {Description: "Embedded adapter schema is invalid"}, }, }} + addAdapterSchemaValidationPath(spec) } func promptRunOperation( diff --git a/pkg/cli/webapp/src/AdapterSchemaPreview.tsx b/pkg/cli/webapp/src/AdapterSchemaPreview.tsx new file mode 100644 index 00000000..a14c7d48 --- /dev/null +++ b/pkg/cli/webapp/src/AdapterSchemaPreview.tsx @@ -0,0 +1,56 @@ +import { useEffect, useId, useRef, useState } from "react"; +import { Button, Field, InputField, JsonSchemaForm, type JsonSchemaObject } from "@flanksource/clicky-ui/components"; +import { createSchemaDraft, editSchemaDraft, type SchemaDraft } from "./adapterSchemaDraft"; +import { validateAdapterSchema, type AdapterSchemaDocument, type SchemaValidation } from "./adapterSchemas"; + +export function AdapterSchemaPreview({ document, view, draft, onChange }: { + document: AdapterSchemaDocument; view: string; draft: SchemaDraft | undefined; onChange: (draft: SchemaDraft) => void; +}) { + const id = useId(); + const current = draft ?? createSchemaDraft({}); + const [result, setResult] = useState(); + const [error, setError] = useState(""); + const [loading, setLoading] = useState(false); + const request = useRef(undefined); + useEffect(() => () => request.current?.abort(), []); + const change = (next: SchemaDraft) => { + request.current?.abort(); + setResult(undefined); setError(""); setLoading(false); onChange(next); + }; + const wrapped = !document.schema.properties || Boolean(document.schema.additionalProperties); + const formSchema: JsonSchemaObject = wrapped ? { + type: "object", properties: { value: document.schema }, + ...(document.schema.$defs ? { $defs: document.schema.$defs } : {}), + ...(document.schema.definitions ? { definitions: document.schema.definitions } : {}), + } : document.schema; + const object = current.value !== null && typeof current.value === "object" && !Array.isArray(current.value); + return
+

Local preview. Values stay in this page and are never saved or applied to a runtime.

+ {view === "form" ? <> + {current.error &&

Correct the JSON or YAML draft before editing the form: {current.error}

} + {!wrapped && !object ?

This resource requires an object. Correct its JSON or YAML value.

: + } + onChange={(value) => change(createSchemaDraft(wrapped ? value.value : value))} readOnly={Boolean(current.error)} + idPrefix={id} layout={{ mode: "stacked", help: "hover" }} size="sm" applyDefaults={false} + {...(result ? { errors: result.errors.map((issue) => ({ ...issue, instancePath: wrapped ? `/value${issue.instancePath}` : issue.instancePath })) } : {})} />} + : + change(editSchemaDraft(current, view === "yaml" ? "yaml" : "json", text))} /> + } + {current.error && view !== "form" &&

{current.error}

} +
+ + {result && {result.valid ? "Schema valid" : `${result.errors.length} validation error${result.errors.length === 1 ? "" : "s"}`}} +
+ {error &&

{error}

} + {result?.errors.map((issue, index) =>

{issue.instancePath || "/"}: {issue.message}

)} +
; +} diff --git a/pkg/cli/webapp/src/AdapterSchemaProvenance.tsx b/pkg/cli/webapp/src/AdapterSchemaProvenance.tsx new file mode 100644 index 00000000..5b30d9df --- /dev/null +++ b/pkg/cli/webapp/src/AdapterSchemaProvenance.tsx @@ -0,0 +1,30 @@ +import type { AdapterSchemaDocument } from "./adapterSchemas"; + +function record(value: unknown): Record { + return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record : {}; +} + +export function AdapterSchemaProvenance({ document }: { document: AdapterSchemaDocument }) { + const schema = document.schema; + const resource = record(schema["x-captain-resource"]); + const inventory = record(schema["x-captain-inventory"]); + const adapter = record(schema["x-captain-adapter"]); + const sources = Array.isArray(adapter.sources) ? adapter.sources : []; + const versions = [resource.version, inventory.version, ...sources.map((source: unknown) => record(source).version)] + .filter((version): version is string => typeof version === "string" && version.length > 0); + const rawLinks = record(schema["x-help"]).links; + if (rawLinks !== undefined && !Array.isArray(rawLinks)) throw new Error("Schema help links must be an array."); + const links = (rawLinks ?? []).map((value: unknown) => { + const link = record(value); + if (typeof link.href !== "string" || typeof link.label !== "string") throw new Error("Schema help links require href and label strings."); + return { href: link.href, label: link.label }; + }); + return
+ {versions.length > 0 &&

Source: {[...new Set(versions)].join(" · ")}

} + {links.map((link) => { + const url = new URL(link.href); + if (!["http:", "https:"].includes(url.protocol)) throw new Error(`Unsupported documentation URL: ${link.href}`); + return {link.label}; + })} +
; +} diff --git a/pkg/cli/webapp/src/AdapterSchemasPage.test.tsx b/pkg/cli/webapp/src/AdapterSchemasPage.test.tsx index ed561ab1..7a507ee5 100644 --- a/pkg/cli/webapp/src/AdapterSchemasPage.test.tsx +++ b/pkg/cli/webapp/src/AdapterSchemasPage.test.tsx @@ -1,9 +1,9 @@ import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; -import { fireEvent, render, screen } from "@testing-library/react"; -import type { PropsWithChildren } from "react"; -import { describe, expect, it, vi } from "vitest"; +import { cleanup, fireEvent, render, screen } from "@testing-library/react"; +import { useState, type PropsWithChildren } from "react"; +import { afterEach, describe, expect, it, vi } from "vitest"; import { AdapterSchemasPage } from "./AdapterSchemasPage"; -import type { AdapterSchemaDocument } from "./adapterSchemas"; +import { parseAdapterSchemaPath, type AdapterSchemaDocument } from "./adapterSchemas"; vi.mock("@flanksource/clicky-ui/data", () => ({ SchemaViewer: ({ schema }: { schema: { title?: string } }) => ( @@ -13,6 +13,7 @@ vi.mock("@flanksource/clicky-ui/data", () => ({ const DOCUMENTS: AdapterSchemaDocument[] = [ { + id: "anthropic/api", kind: "execution", provider: "anthropic", mode: "api", title: "Anthropic API", @@ -20,6 +21,7 @@ const DOCUMENTS: AdapterSchemaDocument[] = [ schema: { type: "object", title: "AnthropicAPIOptions" }, }, { + id: "openai/api", kind: "execution", provider: "openai", mode: "api", title: "OpenAI API", @@ -27,6 +29,7 @@ const DOCUMENTS: AdapterSchemaDocument[] = [ schema: { type: "object", title: "OpenAIAPIOptions" }, }, { + id: "openai/cli", kind: "execution", provider: "openai", mode: "cli", title: "OpenAI CLI", @@ -36,6 +39,7 @@ const DOCUMENTS: AdapterSchemaDocument[] = [ ]; describe("AdapterSchemasPage", () => { + afterEach(cleanup); it("renders the selected schema and keeps provider and mode choices in the route", async () => { const navigate = vi.fn(); vi.stubGlobal("fetch", vi.fn().mockResolvedValue({ @@ -53,12 +57,32 @@ describe("AdapterSchemasPage", () => { expect(await screen.findByRole("heading", { name: "OpenAI CLI" })).toBeInTheDocument(); expect(screen.getByTestId("schema-viewer")).toHaveTextContent("OpenAICLIOptions"); - fireEvent.click(screen.getByRole("radio", { name: "API" })); + fireEvent.change(screen.getByLabelText("Resource"), { target: { value: "openai/api" } }); expect(navigate).toHaveBeenCalledWith("/adapter-schemas/openai/api"); fireEvent.change(screen.getByLabelText("Provider"), { target: { value: "anthropic" } }); expect(navigate).toHaveBeenCalledWith("/adapter-schemas/anthropic/api"); }); + + it("retains separate resource drafts and query state through navigation", async () => { + vi.stubGlobal("fetch", vi.fn().mockResolvedValue({ ok: true, json: async () => DOCUMENTS })); + function Workspace() { + const [location, navigate] = useState("/adapter-schemas/openai/api?view=json&q=API"); + const url = new URL(location, "http://localhost"); + return ; + } + renderPage(); + const input = await screen.findByRole("textbox", { name: "JSON value" }); + fireEvent.change(input, { target: { value: '{"model":"example-model"}' } }); + fireEvent.change(screen.getByLabelText("Resource"), { target: { value: "openai/cli" } }); + expect(screen.getByRole("textbox", { name: "JSON value" })).toHaveValue("{}"); + expect(screen.getByLabelText("Search resources")).toHaveValue("API"); + fireEvent.change(screen.getByLabelText("Resource"), { target: { value: "openai/api" } }); + expect(screen.getByRole("textbox", { name: "JSON value" })).toHaveValue('{"model":"example-model"}'); + fireEvent.change(screen.getByRole("textbox", { name: "JSON value" }), { target: { value: "{" } }); + expect(screen.getByRole("button", { name: "Validate schema" })).toBeDisabled(); + expect(screen.getByRole("alert")).toBeInTheDocument(); + }); }); function renderPage(children: PropsWithChildren["children"]) { diff --git a/pkg/cli/webapp/src/AdapterSchemasPage.tsx b/pkg/cli/webapp/src/AdapterSchemasPage.tsx index 2b9ba5e8..ab3d2b6a 100644 --- a/pkg/cli/webapp/src/AdapterSchemasPage.tsx +++ b/pkg/cli/webapp/src/AdapterSchemasPage.tsx @@ -1,167 +1,99 @@ -import { useId, useMemo } from "react"; +import { useId, useMemo, useState } from "react"; import { useQuery } from "@tanstack/react-query"; -import { - Field, - Panel, - SegmentedControl, - Select, -} from "@flanksource/clicky-ui/components"; +import { Field, InputField, Panel, SegmentedControl, Select } from "@flanksource/clicky-ui/components"; import { SchemaViewer } from "@flanksource/clicky-ui/data"; import { StateMessage } from "./StateMessage"; -import { - adapterSchemaLocation, - fetchAdapterSchemas, - selectAdapterSchema, - type AdapterSchemaDocument, - type AdapterSchemaSelection, -} from "./adapterSchemas"; +import { AdapterSchemaPreview } from "./AdapterSchemaPreview"; +import { AdapterSchemaProvenance } from "./AdapterSchemaProvenance"; +import { adapterSchemaLocation, fetchAdapterSchemas, selectAdapterSchema, type AdapterSchemaDocument, type AdapterSchemaSelection } from "./adapterSchemas"; +import type { SchemaDraft } from "./adapterSchemaDraft"; type Navigate = (to: string, opts?: { replace?: boolean }) => void; const PROVIDER_LABELS: Record = { - anthropic: "Anthropic", - openai: "OpenAI", - google: "Google", - deepseek: "DeepSeek", - jev: "Jev", + anthropic: "Anthropic", openai: "OpenAI", google: "Google", deepseek: "DeepSeek", jev: "Jev", captain: "Captain", }; -export function AdapterSchemasPage({ - selection, - onNavigate, -}: { - selection: AdapterSchemaSelection; - onNavigate: Navigate; -}) { - const query = useQuery({ - queryKey: ["adapter-schemas"], - queryFn: fetchAdapterSchemas, - staleTime: Number.POSITIVE_INFINITY, - }); +export function AdapterSchemasPage({ selection, search = "", onNavigate }: { selection: AdapterSchemaSelection; search?: string; onNavigate: Navigate }) { + const query = useQuery({ queryKey: ["adapter-schemas"], queryFn: fetchAdapterSchemas, staleTime: Number.POSITIVE_INFINITY }); const selected = selectAdapterSchema(query.data ?? [], selection); - - return ( -
-
-
-

- Captain · /adapter-schemas -

-

Adapter schemas

-

- Inspect the native API, agent protocol, and CLI options Captain maps for every runtime. - Read-only and managed options remain visible alongside JsonSchemaForm annotations. -

-
- - {query.isLoading ? ( - Loading native runtime schemas... - ) : query.error ? ( - {errorMessage(query.error)} - ) : selected && query.data ? ( - - ) : ( - The adapter schema catalog returned no schemas. - )} -
+ return
+
+
+

Adapter schemas

+

Explore native provider resources and portable Captain configuration. Try form inputs locally and inspect their JSON or YAML.

+
+ {query.isLoading ? Loading schemas... + : query.error ? {errorMessage(query.error)} + : selected && query.data ? + : {query.data?.length ? `Unknown schema: ${selection.provider}/${selection.mode}` : "The schema catalog returned no schemas."}}
- ); +
; } -function AdapterSchemaWorkspace({ - documents, - selected, - onNavigate, -}: { - documents: AdapterSchemaDocument[]; - selected: AdapterSchemaDocument; - onNavigate: Navigate; +function AdapterSchemaWorkspace({ documents, selected, locationSearch, onNavigate }: { + documents: AdapterSchemaDocument[]; selected: AdapterSchemaDocument; locationSearch: string; onNavigate: Navigate; }) { - const providerId = useId(); - const providers = useMemo( - () => [...new Set(documents.map((document) => document.provider))], - [documents], - ); - const modes = documents.filter((document) => document.provider === selected.provider); - const navigate = (provider: string, mode: string) => - onNavigate(adapterSchemaLocation({ provider, mode })); - - return ( -
- -
- - ({ value: provider, label: PROVIDER_LABELS[provider] ?? provider }))} + onChange={(event) => { + const first = documents.find((document) => document.provider === event.target.value); + if (!first) throw new Error(`Provider ${event.target.value} has no schemas`); + navigate(first); + }} /> + + updateQuery("q", value)} /> + +