diff --git a/README.md b/README.md index 46483a8c..6b42bf42 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,7 @@ Kernel provides sandboxed, ready-to-use Chrome browsers for browser automations - Invoke app actions (sync or async) and stream logs - Create, list, view, and delete managed browser sessions - Get a live view URL for visual monitoring and remote control +- Search the web across providers and retrieve page content for results ## Installation @@ -298,8 +299,17 @@ populated, not that login succeeded. `fill` requires an already-open page and ne navigates or submits it. Optional `page_url` selects the exact page; cards require it. Do not automatically retry failed/unknown fills or fall back to aliases. +Create specs list `fields` as an ordered array. Each entry carries a stable `name` +(letters, digits, and underscores, starting with a letter) that keys values, updates, +and fills. Order is preserved: list fields in the same top-to-bottom order as the +website, because the collection form renders that order unchanged. An optional `label` +supplies non-secret display text for that field on the collection form; it never +affects value keys, updates, or fills. Use a single trimmed line of at most 128 UTF-8 +bytes, and it is returned as metadata in `get`/`list` output. + Use `credentials update --version --spec-file changes.json` -with a spec such as `{"fields":{"password":{"value":"replacement"}}}`. Keep actual +with a spec such as `{"fields":{"password":{"value":"replacement"}}}`; update specs key +`fields` by name rather than using the ordered array. Keep actual secrets in protected files or stdin, never shell arguments. Omission preserves values; null or an empty string clears supported fields, including required text/email/password fields (returning them to pending collection). The form still requires nonempty required inputs. Field definitions cannot change. Stale versions fail, without retries. `items invoke collect` reopens the full form without @@ -560,14 +570,21 @@ kernel vaults items get user-123 order-1 --wait 60 -o json this vault attached. `merchant_origin` is the canonical HTTPS origin of the top-level merchant document, not a processor iframe; HTTP localhost is allowed for tests. -Optional `psp` selects the tokenization processor: `square`, `braintree`, `worldpay`, -`bambora`, or `mercado_pago`. Omit it for Square; non-Square processors require +Optional `psp` selects the checkout processor: `square`, `braintree`, `worldpay`, +`bambora`, `mercado_pago`, or `adyen`. Omit it for Square; non-Square processors require multi-processor preparation enablement. `environment` is `production`, `sandbox`, or -`shared`: use `production` or `sandbox` for Square, Braintree and Worldpay, and `shared` -for Bambora and Mercado Pago. Shared endpoints do not establish test mode; merchant +`shared`: use `production` or `sandbox` for Square, Braintree, Worldpay and Adyen, and +`shared` for Bambora and Mercado Pago. Shared endpoints do not establish test mode; merchant credentials and configuration determine processor test mode, independently of the AgentCard credential mode. +`adyen` supports fresh-card Sessions requests on Adyen hosts only. Fill the public dummy +card fields rather than vault aliases, and keep the approval page open through device +handoff, including Adyen encryption. The unique armed preparation is associated with the +next eligible request from the declared browser and merchant origin; competing preparations +are rejected. Adyen device approval and browser `Authorised` responses are not capture or +fulfillment evidence. + Keep the approval page open. Poll until the item's status is `ready_to_submit`, then submit native Pay before `state.preparation.expires_at`. Readiness lasts at most 30 seconds, and polling does not extend it. The CLI displays the preparation ID, status, @@ -1153,6 +1170,50 @@ Automated authentication for web services. The `run` command orchestrates the fu - `--default-project-max-concurrent-sessions ` - Default maximum concurrent browsers for projects without an explicit override (`0` to remove the default) - `--output json`, `-o json` - Output raw JSON object +### Search + +- `kernel search ` - Search the web through Kernel's search providers + - `--country ` - ISO 3166-1 alpha-2 search locale preference + - `--language ` - BCP 47 search language preference + - `--max-results ` - Requested result count, 1-100 (clamped to the serving provider's cap) + - `--recency ` - Relative search window: `hour`, `day`, `week`, `month`, or `year` + - `--safe-search ` - Safety preference: `off`, `moderate`, or `strict` + - `--start-date ` / `--end-date ` - Inclusive publication-date bounds (`--recency` takes precedence) + - `--include-domains ` / `--exclude-domains ` - Hostname preferences, matching a hostname and its subdomains + - `--strict-params` - Require every supplied portable parameter to be honored exactly instead of approximated + - `--include-raw` - Include untouched provider payloads in the response's raw fields + - `--timeout-ms ` - Overall deadline across search attempts and inline retrieval + - `--content` - Retrieve page content for each result using portable defaults + - `--show-content` - Print the extracted content text for each result (implies `--content`) + - `--content-source ` - Retrieval source: `auto`, `provider`, or `browser` + - `--content-format ` - Extracted content format: `markdown` or `text` + - `--content-max-chars ` - Per-result Unicode character limit after extraction + - `--content-max-age-hours ` - Maximum acceptable age of cached page content; `0` forces a live fetch + - `--content-timeout-ms ` - Per-result retrieval deadline + - `--content-browser-id ` - Retrieve through an existing browser session (requires `--content-source browser`) + - `--content-browser-mode ` - Browser retrieval mode: `curl` or `render` + - `--provider ` - Pin a single provider (`brave`, `exa`, `perplexity`, `context`, `parallel`, `valyu`, `octen`, `you`, `tavily`, `serpapi`) + - `--fallback-providers ` - Ordered provider chain to try in turn + - `--fallback-on ` - Outcomes that advance to the next provider: `error`, `timeout`, `empty` + - `--provider-options ` - Provider-native options as a JSON object keyed by provider slug + - `--output json`, `-o json` - Output raw JSON object +- `kernel search get ` - Re-read a retained search without calling a provider or incurring cost + - `--show-content` - Print the extracted content text for each result + - `--output json`, `-o json` - Output raw JSON object +- `kernel search providers` - List providers, result caps, and content capabilities + - `--slug ` - Filter to a single provider; also prints its portable-parameter support matrix and notes + - `--output json`, `-o json` - Output raw JSON array +- `kernel search contents ` - Deferred content retrieval for a retained search + - `--result-ids ` - Result IDs from the retained search, in the desired response order + - `--limit ` - Number of results to fetch starting from rank 1 (mutually exclusive with `--result-ids`) + - `--timeout-ms ` - Overall deadline across all selected results + - Accepts the same `--content-*` flags as `kernel search` + - This endpoint is reserved and returns 404 until deferred retrieval ships; use `kernel search --content` for inline retrieval + +Searches are retained for 24 hours. Omitting the strategy flags lets Kernel pick an +eligible provider; portable filters a provider cannot honor are approximated or +dropped and reported as warnings unless `--strict-params` is set. + ## Examples ### Create a new app diff --git a/cmd/auth_connections.go b/cmd/auth_connections.go index be139f69..f1c17ed9 100644 --- a/cmd/auth_connections.go +++ b/cmd/auth_connections.go @@ -122,6 +122,7 @@ type AuthConnectionLoginInput struct { Region string Stealth BoolFlag RecordSession BoolFlag + SkillMode string Telemetry string TelemetryCdpExclude string TelemetryExport string @@ -794,6 +795,20 @@ func (c AuthConnectionCmd) Delete(ctx context.Context, in AuthConnectionDeleteIn return nil } +// parseSkillModeFlag validates the --skill-mode value against the modes the API +// accepts for a login, so a typo fails locally instead of starting a flow with +// the wrong skill behavior. +func parseSkillModeFlag(mode string) (kernel.AuthConnectionLoginParamsSkillMode, error) { + switch kernel.AuthConnectionLoginParamsSkillMode(mode) { + case kernel.AuthConnectionLoginParamsSkillModeEnabled: + return kernel.AuthConnectionLoginParamsSkillModeEnabled, nil + case kernel.AuthConnectionLoginParamsSkillModeDisabled: + return kernel.AuthConnectionLoginParamsSkillModeDisabled, nil + default: + return "", fmt.Errorf("invalid --skill-mode value: %s (must be one of enabled, disabled)", mode) + } +} + func (c AuthConnectionCmd) Login(ctx context.Context, in AuthConnectionLoginInput) error { if err := validateJSONOutput(in.Output); err != nil { return err @@ -825,6 +840,14 @@ func (c AuthConnectionCmd) Login(ctx context.Context, in AuthConnectionLoginInpu params.RecordSession = kernel.Opt(in.RecordSession.Value) } + if in.SkillMode != "" { + mode, err := parseSkillModeFlag(in.SkillMode) + if err != nil { + return err + } + params.SkillMode = mode + } + if in.Telemetry != "" || in.TelemetryCdpExclude != "" || in.TelemetryExport != "" { t, err := buildManagedAuthTelemetryParam(in.Telemetry, in.TelemetryCdpExclude, in.TelemetryExport, false) if err != nil { @@ -1069,7 +1092,7 @@ func (c AuthConnectionCmd) Timeline(ctx context.Context, in AuthConnectionTimeli return nil } - tableData := pterm.TableData{{"Timestamp", "Type", "Status", "Step", "Browser Session", "Telemetry", "Details"}} + tableData := pterm.TableData{{"Timestamp", "Completed", "Type", "Status", "Step", "Browser Session", "Telemetry", "Details"}} for _, e := range events { details := e.ErrorMessage if details == "" { @@ -1087,6 +1110,9 @@ func (c AuthConnectionCmd) Timeline(ctx context.Context, in AuthConnectionTimeli } tableData = append(tableData, []string{ util.FormatLocal(e.Timestamp), + // Absent (dashed out) for in-progress attempts, health checks, and + // older attempts recorded before completion times were persisted. + util.FormatLocal(e.CompletedAt), string(e.Type), string(e.Status), string(e.Step), @@ -1381,6 +1407,7 @@ func init() { authConnectionsLoginCmd.Flags().String("region", "", "Geographic region override for this login: 'us-east', 'eu-west', or 'ap-southeast'") authConnectionsLoginCmd.Flags().Bool("stealth", true, "Override stealth mode for this login's browser session; use --stealth=false to disable") authConnectionsLoginCmd.Flags().Bool("record-session", false, "Override whether this login's browser session is recorded; use --record-session=false to disable") + authConnectionsLoginCmd.Flags().String("skill-mode", "", "Whether this login reads and writes learned domain skills: 'enabled' (default) or 'disabled'. Automatic reauths inherit the selected mode until a later accepted login sets enabled or omits the flag") authConnectionsLoginCmd.Flags().String("telemetry", "", "Telemetry override for this login only, merged onto the connection's config: --telemetry=all, --telemetry=off, or --telemetry=console,network") authConnectionsLoginCmd.Flags().String("telemetry-export-otlp", "", "Export override for this login only: an OTLP destination ID or name; --telemetry-export-otlp=off disables export for this login. Naming a destination requires passing --telemetry in the same command, since export and capture are validated together") authConnectionsLoginCmd.Flags().String("telemetry-cdp-exclude", "", "Leave the named CDP methods out of control telemetry's cdp_command events, comma-separated (e.g. Input.dispatchMouseEvent,Page.captureScreenshot); --telemetry-cdp-exclude=none clears the list. Excluded commands are still relayed to the browser, they just produce no event") @@ -1600,6 +1627,7 @@ func runAuthConnectionsLogin(cmd *cobra.Command, args []string) error { proxyName, _ := cmd.Flags().GetString("proxy-name") proxyMode, _ := cmd.Flags().GetString("proxy-mode") region, _ := cmd.Flags().GetString("region") + skillMode, _ := cmd.Flags().GetString("skill-mode") telemetry, _ := cmd.Flags().GetString("telemetry") telemetryCdpExclude, _ := cmd.Flags().GetString("telemetry-cdp-exclude") telemetryExport, _ := cmd.Flags().GetString("telemetry-export-otlp") @@ -1614,6 +1642,7 @@ func runAuthConnectionsLogin(cmd *cobra.Command, args []string) error { Region: region, Stealth: readBoolFlag(cmd.Flags(), "stealth"), RecordSession: readBoolFlag(cmd.Flags(), "record-session"), + SkillMode: skillMode, Telemetry: telemetry, TelemetryCdpExclude: telemetryCdpExclude, TelemetryExport: telemetryExport, diff --git a/cmd/auth_connections_test.go b/cmd/auth_connections_test.go index f23888c3..339a4aa8 100644 --- a/cmd/auth_connections_test.go +++ b/cmd/auth_connections_test.go @@ -10,6 +10,7 @@ import ( "net/http/httptest" "os" "testing" + "time" "github.com/kernel/cli/pkg/util" "github.com/kernel/kernel-go-sdk" @@ -1223,7 +1224,8 @@ func TestTimeline_RendersEventsAndPagination(t *testing.T) { "type": "login", "status": "SUCCESS", "browser_session_id": "browser_1", - "telemetry_captured": true + "telemetry_captured": true, + "completed_at": "2026-09-21T12:00:00Z" }`), &loginEvent)) fake := &FakeAuthConnectionService{ TimelineFunc: func(ctx context.Context, id string, query kernel.AuthConnectionTimelineParams, opts ...option.RequestOption) (*pagination.OffsetPagination[kernel.ManagedAuthTimelineEvent], error) { @@ -1252,6 +1254,9 @@ func TestTimeline_RendersEventsAndPagination(t *testing.T) { // Telemetry capture is reported for events that have a browser session. assert.Contains(t, out, "Telemetry") assert.Regexp(t, `browser_1.*yes`, out) + // completed_at is shown for terminal attempts and dashed out otherwise. + assert.Contains(t, out, "Completed") + assert.Contains(t, out, util.FormatLocal(time.Date(2026, 9, 21, 12, 0, 0, 0, time.UTC))) // The third event is truncated off the page. assert.NotContains(t, out, "health_check") assert.Contains(t, out, "Has more: yes") @@ -1390,3 +1395,43 @@ func TestAuthConnectionsGet_TelemetryRowOmittedWhenOff(t *testing.T) { require.NoError(t, c.Get(context.Background(), AuthConnectionGetInput{ID: "conn-1"})) assert.NotContains(t, outBuf.String(), "Browser Telemetry") } + +func TestLogin_SkillMode(t *testing.T) { + capturePtermOutput(t) + var captured kernel.AuthConnectionLoginParams + fake := &FakeAuthConnectionService{ + LoginFunc: func(ctx context.Context, id string, body kernel.AuthConnectionLoginParams, opts ...option.RequestOption) (*kernel.LoginResponse, error) { + captured = body + return &kernel.LoginResponse{ID: id}, nil + }, + } + c := AuthConnectionCmd{svc: fake} + require.NoError(t, c.Login(context.Background(), AuthConnectionLoginInput{ID: "auth_1", SkillMode: "disabled"})) + assert.Equal(t, kernel.AuthConnectionLoginParamsSkillModeDisabled, captured.SkillMode) +} + +// Omitting --skill-mode leaves the field unset, so the API keeps its default of +// enabled rather than the CLI pinning a mode the user never asked for. +func TestLogin_SkillModeOmitted(t *testing.T) { + capturePtermOutput(t) + var captured kernel.AuthConnectionLoginParams + fake := &FakeAuthConnectionService{ + LoginFunc: func(ctx context.Context, id string, body kernel.AuthConnectionLoginParams, opts ...option.RequestOption) (*kernel.LoginResponse, error) { + captured = body + return &kernel.LoginResponse{ID: id}, nil + }, + } + c := AuthConnectionCmd{svc: fake} + require.NoError(t, c.Login(context.Background(), AuthConnectionLoginInput{ID: "auth_1"})) + assert.Empty(t, string(captured.SkillMode)) +} + +func TestLogin_InvalidSkillModeErrors(t *testing.T) { + capturePtermOutput(t) + c := AuthConnectionCmd{svc: &FakeAuthConnectionService{}} + + err := c.Login(context.Background(), AuthConnectionLoginInput{ID: "auth_1", SkillMode: "mars"}) + + require.Error(t, err) + assert.Contains(t, err.Error(), "invalid --skill-mode value") +} diff --git a/cmd/org.go b/cmd/org.go index 2bce469d..92143ade 100644 --- a/cmd/org.go +++ b/cmd/org.go @@ -135,6 +135,16 @@ func renderOrgLimits(limits *kernel.OrgLimits) { {"Default Project Max Concurrent Sessions", formatProjectLimitValue(limits.DefaultProjectMaxConcurrentSessions, limits.JSON.DefaultProjectMaxConcurrentSessions)}, } + // Concurrency usage is measured live and only returned by newer API + // versions. Unlike the limit rows, a null here means usage could not be + // read rather than "unlimited", so render it as unknown. + if orgLimitFieldPresent(limits.JSON.ConcurrentSessionsUsed) { + rows = append(rows, []string{"Concurrent Sessions Used", formatOrgUsageValue(limits.ConcurrentSessionsUsed, limits.JSON.ConcurrentSessionsUsed)}) + } + if orgLimitFieldPresent(limits.JSON.ConcurrentSessionsAvailable) { + rows = append(rows, []string{"Concurrent Sessions Available", formatOrgUsageValue(limits.ConcurrentSessionsAvailable, limits.JSON.ConcurrentSessionsAvailable)}) + } + // Managed auth limits are plan-derived and only returned by newer API // versions, so render each row only when the field is present. A null // max_auth_connections means unlimited, so presence — not validity — is the @@ -167,6 +177,15 @@ func orgLimitFieldPresent(field respjson.Field) bool { return field.Raw() != respjson.Omitted } +// formatOrgUsageValue renders a live usage counter, where a null means the API +// could not read current usage rather than "unlimited". +func formatOrgUsageValue(value int64, field respjson.Field) string { + if !field.Valid() { + return "unknown" + } + return fmt.Sprintf("%d", value) +} + func renderOrgEntitlements(entitlements *kernel.OrgEntitlements) { if entitlements == nil { pterm.Info.Println("No organization entitlements found") @@ -266,7 +285,7 @@ var orgLimitsCmd = &cobra.Command{ var orgLimitsGetCmd = &cobra.Command{ Use: "get", Short: "Get organization limits", - Long: "Show the organization's effective limits: the concurrency limit, the default per-project cap applied to projects without an explicit override, and the plan-derived managed auth and vault limits along with current auth connection and vault usage.", + Long: "Show the organization's effective limits: the concurrency limit, current organization-wide concurrent browser usage and remaining capacity, the default per-project cap applied to projects without an explicit override, and the plan-derived managed auth and vault limits along with current auth connection and vault usage.", Args: cobra.NoArgs, RunE: runOrgLimitsGet, } diff --git a/cmd/org_test.go b/cmd/org_test.go index 9118f619..33afdbbd 100644 --- a/cmd/org_test.go +++ b/cmd/org_test.go @@ -4,6 +4,7 @@ import ( "context" "encoding/json" "errors" + "strings" "testing" "time" @@ -296,6 +297,63 @@ func TestOrgLimitsGet_NullDefaultShownAsUnlimited(t *testing.T) { assert.Contains(t, buf.String(), "unlimited") } +func TestOrgLimitsGet_RendersConcurrencyUsage(t *testing.T) { + buf := capturePtermOutput(t) + fake := &FakeOrgLimitsService{ + GetFunc: func(ctx context.Context, opts ...option.RequestOption) (*kernel.OrgLimits, error) { + limits := &kernel.OrgLimits{ + MaxConcurrentSessions: 100, + ConcurrentSessionsUsed: 12, + ConcurrentSessionsAvailable: 88, + } + limits.JSON.ConcurrentSessionsUsed = respjson.NewField("12") + limits.JSON.ConcurrentSessionsAvailable = respjson.NewField("88") + return limits, nil + }, + } + c := OrgCmd{limits: fake} + assert.NoError(t, c.LimitsGet(context.Background(), OrgLimitsGetInput{})) + + out := buf.String() + assert.Contains(t, out, "Concurrent Sessions Used") + assert.Contains(t, out, "12") + assert.Contains(t, out, "Concurrent Sessions Available") + assert.Contains(t, out, "88") +} + +func TestOrgLimitsGet_NullConcurrencyUsageShownAsUnknown(t *testing.T) { + buf := capturePtermOutput(t) + fake := &FakeOrgLimitsService{ + GetFunc: func(ctx context.Context, opts ...option.RequestOption) (*kernel.OrgLimits, error) { + limits := &kernel.OrgLimits{MaxConcurrentSessions: 100} + // Null (not omitted) means usage could not be read, which is not + // the same as unlimited. + limits.JSON.ConcurrentSessionsUsed = respjson.NewField(respjson.Null) + limits.JSON.ConcurrentSessionsAvailable = respjson.NewField(respjson.Null) + return limits, nil + }, + } + c := OrgCmd{limits: fake} + assert.NoError(t, c.LimitsGet(context.Background(), OrgLimitsGetInput{})) + + out := buf.String() + // Both usage rows render as unknown rather than borrowing the "unlimited" + // meaning a null limit would have. + assert.Contains(t, out, "Concurrent Sessions Used") + assert.Contains(t, out, "Concurrent Sessions Available") + assert.Equal(t, 2, strings.Count(out, "unknown")) +} + +func TestOrgLimitsGet_OmitsConcurrencyUsageRowsWhenAbsent(t *testing.T) { + buf := capturePtermOutput(t) + c := OrgCmd{limits: &FakeOrgLimitsService{}} + assert.NoError(t, c.LimitsGet(context.Background(), OrgLimitsGetInput{})) + + out := buf.String() + assert.NotContains(t, out, "Concurrent Sessions Used") + assert.NotContains(t, out, "Concurrent Sessions Available") +} + func TestOrgLimitsGet_RendersManagedAuthLimits(t *testing.T) { buf := capturePtermOutput(t) fake := &FakeOrgLimitsService{ diff --git a/cmd/root.go b/cmd/root.go index 5b34a49c..90518223 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -169,6 +169,7 @@ func init() { rootCmd.AddCommand(proxies.ProxiesCmd) rootCmd.AddCommand(extensionsCmd) rootCmd.AddCommand(credentialsCmd) + rootCmd.AddCommand(searchCmd) rootCmd.AddCommand(credentialProvidersCmd) rootCmd.AddCommand(createCmd) rootCmd.AddCommand(mcp.MCPCmd) diff --git a/cmd/search.go b/cmd/search.go new file mode 100644 index 00000000..51a9b90b --- /dev/null +++ b/cmd/search.go @@ -0,0 +1,900 @@ +package cmd + +import ( + "context" + "encoding/json" + "fmt" + "strconv" + "strings" + "time" + + "github.com/kernel/cli/pkg/util" + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + "github.com/kernel/kernel-go-sdk/packages/param" + "github.com/pterm/pterm" + "github.com/spf13/cobra" +) + +// SearchService defines the subset of the Kernel SDK search client that we use. +type SearchService interface { + New(ctx context.Context, body kernel.SearchNewParams, opts ...option.RequestOption) (res *kernel.Search, err error) + Get(ctx context.Context, id string, opts ...option.RequestOption) (res *kernel.Search, err error) +} + +// SearchProvidersService defines the subset of the Kernel SDK search provider +// client that we use. +type SearchProvidersService interface { + List(ctx context.Context, query kernel.SearchProviderListParams, opts ...option.RequestOption) (res *[]kernel.Provider, err error) +} + +// SearchContentsService defines the subset of the Kernel SDK search contents +// client that we use. +type SearchContentsService interface { + Fetch(ctx context.Context, id string, body kernel.SearchContentFetchParams, opts ...option.RequestOption) (err error) +} + +// searchProviderSlugs are the concrete providers accepted by --provider, +// --fallback-providers, and the providers --slug filter. Auto and fallback are +// strategies rather than provider entries, so they are not listed here. +var searchProviderSlugs = []string{ + string(kernel.SearchProviderListParamsSlugBrave), + string(kernel.SearchProviderListParamsSlugExa), + string(kernel.SearchProviderListParamsSlugPerplexity), + string(kernel.SearchProviderListParamsSlugContext), + string(kernel.SearchProviderListParamsSlugParallel), + string(kernel.SearchProviderListParamsSlugValyu), + string(kernel.SearchProviderListParamsSlugOcten), + string(kernel.SearchProviderListParamsSlugYou), + string(kernel.SearchProviderListParamsSlugTavily), + string(kernel.SearchProviderListParamsSlugSerpapi), +} + +var ( + searchRecencyValues = []string{"hour", "day", "week", "month", "year"} + searchSafeSearchValues = []string{"off", "moderate", "strict"} + searchContentSources = []string{"auto", "provider", "browser"} + searchContentFormats = []string{"markdown", "text"} + searchBrowserModes = []string{"curl", "render"} + searchFallbackOnValues = []string{"error", "timeout", "empty"} + searchDateLayout = "2006-01-02" + searchProviderOptsUsage = `Provider-native options as a JSON object keyed by provider slug, e.g. '{"tavily":{"include_answer":true}}'` +) + +// searchContentInput holds the portable content-retrieval options shared by +// `kernel search` and `kernel search contents`. +type searchContentInput struct { + Enabled bool + Source string + Format string + MaxChars int64 + MaxAgeHours *int64 + TimeoutMs int64 + BrowserID string + BrowserMode string +} + +// requested reports whether the user asked for content retrieval at all. +func (c searchContentInput) requested() bool { + return c.Enabled || c.customized() +} + +// customized reports whether any option beyond the bare --content toggle was set, +// which means the options object must be sent rather than the boolean shorthand. +func (c searchContentInput) customized() bool { + return c.Source != "" || c.Format != "" || c.MaxChars > 0 || c.MaxAgeHours != nil || + c.TimeoutMs > 0 || c.BrowserID != "" || c.BrowserMode != "" +} + +func (c searchContentInput) validate() error { + if err := validateSearchEnum("--content-source", c.Source, searchContentSources); err != nil { + return err + } + if err := validateSearchEnum("--content-format", c.Format, searchContentFormats); err != nil { + return err + } + if err := validateSearchEnum("--content-browser-mode", c.BrowserMode, searchBrowserModes); err != nil { + return err + } + if c.BrowserID != "" && c.Source == "provider" { + return fmt.Errorf("--content-browser-id requires --content-source browser") + } + return nil +} + +type SearchQueryInput struct { + Query string + Output string + Country string + Language string + MaxResults int64 + Recency string + SafeSearch string + StartDate string + EndDate string + IncludeDomains []string + ExcludeDomains []string + StrictParams bool + IncludeRaw bool + TimeoutMs int64 + ShowContent bool + + Content searchContentInput + + Provider string + FallbackProviders []string + FallbackOn []string + ProviderOptions string +} + +type SearchGetInput struct { + ID string + Output string + ShowContent bool +} + +type SearchProvidersInput struct { + Slug string + Output string +} + +type SearchContentsInput struct { + ID string + Output string + ResultIDs []string + Limit int64 + TimeoutMs int64 + Content searchContentInput +} + +// SearchCmd handles search operations independent of cobra. +type SearchCmd struct { + search SearchService + providers SearchProvidersService + contents SearchContentsService +} + +func (s SearchCmd) Query(ctx context.Context, in SearchQueryInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + if strings.TrimSpace(in.Query) == "" { + return fmt.Errorf("a search query is required") + } + if err := validateSearchEnum("--recency", in.Recency, searchRecencyValues); err != nil { + return err + } + if err := validateSearchEnum("--safe-search", in.SafeSearch, searchSafeSearchValues); err != nil { + return err + } + if in.MaxResults < 0 || in.MaxResults > 100 { + return fmt.Errorf("--max-results must be between 1 and 100") + } + if err := in.Content.validate(); err != nil { + return err + } + + req := kernel.RequestParam{Query: in.Query} + if in.Country != "" { + req.Country = kernel.Opt(in.Country) + } + if in.Language != "" { + req.Language = kernel.Opt(in.Language) + } + if in.MaxResults > 0 { + req.MaxResults = kernel.Opt(in.MaxResults) + } + if in.TimeoutMs > 0 { + req.TimeoutMs = kernel.Opt(in.TimeoutMs) + } + if in.StrictParams { + req.StrictParams = kernel.Opt(true) + } + if in.IncludeRaw { + req.IncludeRaw = kernel.Opt(true) + } + if in.Recency != "" { + req.Recency = kernel.RequestRecency(in.Recency) + } + if in.SafeSearch != "" { + req.SafeSearch = kernel.RequestSafeSearch(in.SafeSearch) + } + if in.StartDate != "" { + t, err := parseSearchDate("--start-date", in.StartDate) + if err != nil { + return err + } + req.StartDate = kernel.Opt(t) + } + if in.EndDate != "" { + t, err := parseSearchDate("--end-date", in.EndDate) + if err != nil { + return err + } + req.EndDate = kernel.Opt(t) + } + if len(in.IncludeDomains) > 0 { + req.IncludeDomains = in.IncludeDomains + } + if len(in.ExcludeDomains) > 0 { + req.ExcludeDomains = in.ExcludeDomains + } + + if in.Content.requested() { + if in.Content.customized() { + opts := kernel.RequestContentSearchContentOptionsParam{} + applySearchContentOptions(in.Content, &opts.Source, &opts.Format, &opts.MaxChars, &opts.MaxAgeHours, &opts.TimeoutMs) + if in.Content.BrowserID != "" { + opts.Browser.BrowserID = kernel.Opt(in.Content.BrowserID) + } + if in.Content.BrowserMode != "" { + opts.Browser.Mode = in.Content.BrowserMode + } + req.Content = kernel.RequestContentUnionParam{OfRequestContentSearchContentOptions: &opts} + } else { + req.Content = kernel.RequestContentUnionParam{OfRequestContentBoolean: kernel.Opt(true)} + } + } + + strategy, err := buildSearchStrategy(in.Provider, in.FallbackProviders, in.FallbackOn, in.ProviderOptions) + if err != nil { + return err + } + if strategy != nil { + req.Strategy = *strategy + } + + if in.Output != "json" { + pterm.Info.Printf("Searching for %q...\n", in.Query) + } + + result, err := s.search.New(ctx, kernel.SearchNewParams{Request: req}) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + + return renderSearch(result, in.Output, in.ShowContent) +} + +func (s SearchCmd) Get(ctx context.Context, in SearchGetInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + + result, err := s.search.Get(ctx, in.ID) + if err != nil { + if util.IsNotFound(err) { + if in.Output == "json" { + fmt.Println("null") + return nil + } + pterm.Error.Printf("Search '%s' not found or expired\n", in.ID) + return nil + } + return util.CleanedUpSdkError{Err: err} + } + + return renderSearch(result, in.Output, in.ShowContent) +} + +func (s SearchCmd) Providers(ctx context.Context, in SearchProvidersInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + if err := validateSearchEnum("--slug", in.Slug, searchProviderSlugs); err != nil { + return err + } + + params := kernel.SearchProviderListParams{} + if in.Slug != "" { + params.Slug = kernel.SearchProviderListParamsSlug(in.Slug) + } + + res, err := s.providers.List(ctx, params) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + + var items []kernel.Provider + if res != nil { + items = *res + } + + if in.Output == "json" { + if len(items) == 0 { + fmt.Println("[]") + return nil + } + return util.PrintPrettyJSONSlice(items) + } + + if len(items) == 0 { + pterm.Info.Println("No search providers found") + return nil + } + + rows := pterm.TableData{{"Slug", "Max Results", "Inline Content", "Post-hoc Content", "Freshness Control", "Options Schema"}} + for _, p := range items { + rows = append(rows, []string{ + p.Slug, + strconv.FormatInt(p.MaxResultsCap, 10), + formatSearchBool(p.Content.Inline), + formatSearchBool(p.Content.PostHoc), + formatSearchBool(p.Content.FreshnessControl), + orSearchDash(p.ProviderOptions.SchemaRef), + }) + } + PrintTableNoPad(rows, true) + + // The portable-parameter support matrix and notes only fit in a readable way + // when a single provider was requested. + if len(items) == 1 { + p := items[0] + paramRows := pterm.TableData{{"Portable Param", "Support", "Notes"}} + for _, pp := range []struct { + name string + support string + notes string + }{ + {"country", p.Params.Country.Support, p.Params.Country.Notes}, + {"end_date", p.Params.EndDate.Support, p.Params.EndDate.Notes}, + {"exclude_domains", p.Params.ExcludeDomains.Support, p.Params.ExcludeDomains.Notes}, + {"include_domains", p.Params.IncludeDomains.Support, p.Params.IncludeDomains.Notes}, + {"language", p.Params.Language.Support, p.Params.Language.Notes}, + {"recency", p.Params.Recency.Support, p.Params.Recency.Notes}, + {"safe_search", p.Params.SafeSearch.Support, p.Params.SafeSearch.Notes}, + {"start_date", p.Params.StartDate.Support, p.Params.StartDate.Notes}, + } { + paramRows = append(paramRows, []string{pp.name, orSearchDash(pp.support), orSearchDash(pp.notes)}) + } + pterm.Println() + PrintTableNoPad(paramRows, true) + + if len(p.Notes) > 0 { + pterm.Println() + pterm.Println("Notes:") + for _, n := range p.Notes { + pterm.Printf(" - %s\n", n) + } + } + } + + return nil +} + +func (s SearchCmd) Contents(ctx context.Context, in SearchContentsInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + if len(in.ResultIDs) > 0 && in.Limit > 0 { + return fmt.Errorf("--result-ids and --limit are mutually exclusive") + } + if err := in.Content.validate(); err != nil { + return err + } + + req := kernel.FetchRequestParam{} + if in.Limit > 0 { + req.Limit = kernel.Opt(in.Limit) + } + if in.TimeoutMs > 0 { + req.TimeoutMs = kernel.Opt(in.TimeoutMs) + } + if len(in.ResultIDs) > 0 { + req.ResultIDs = in.ResultIDs + } + if in.Content.customized() { + applySearchContentOptions(in.Content, &req.Content.Source, &req.Content.Format, &req.Content.MaxChars, &req.Content.MaxAgeHours, &req.Content.TimeoutMs) + if in.Content.BrowserID != "" { + req.Content.Browser.BrowserID = kernel.Opt(in.Content.BrowserID) + } + if in.Content.BrowserMode != "" { + req.Content.Browser.Mode = in.Content.BrowserMode + } + } + + if err := s.contents.Fetch(ctx, in.ID, kernel.SearchContentFetchParams{FetchRequest: req}); err != nil { + return util.CleanedUpSdkError{Err: err} + } + + if in.Output == "json" { + fmt.Println("null") + return nil + } + pterm.Success.Printf("Requested content for search %s\n", in.ID) + return nil +} + +// applySearchContentOptions copies the shared content options onto the +// destination fields of either content options struct. The two SDK structs are +// identical in shape but distinct types, so the fields are passed by pointer. +func applySearchContentOptions(in searchContentInput, source, format *string, maxChars, maxAgeHours, timeoutMs *param.Opt[int64]) { + if in.Source != "" { + *source = in.Source + } + if in.Format != "" { + *format = in.Format + } + if in.MaxChars > 0 { + *maxChars = kernel.Opt(in.MaxChars) + } + // 0 is meaningful here (it forces a live fetch), so only the pointer tells us + // whether the flag was supplied. + if in.MaxAgeHours != nil { + *maxAgeHours = kernel.Opt(*in.MaxAgeHours) + } + if in.TimeoutMs > 0 { + *timeoutMs = kernel.Opt(in.TimeoutMs) + } +} + +// buildSearchStrategy maps the strategy flags onto one of the three SDK strategy +// variants. Returns nil when no strategy flag was supplied, which lets the API +// apply its auto default. +func buildSearchStrategy(provider string, fallbackProviders, fallbackOn []string, providerOptions string) (*kernel.StrategyUnionParam, error) { + if provider != "" && len(fallbackProviders) > 0 { + return nil, fmt.Errorf("--provider and --fallback-providers are mutually exclusive") + } + if err := validateSearchEnum("--provider", provider, searchProviderSlugs); err != nil { + return nil, err + } + for _, p := range fallbackProviders { + if err := validateSearchEnum("--fallback-providers", p, searchProviderSlugs); err != nil { + return nil, err + } + } + for _, f := range fallbackOn { + if err := validateSearchEnum("--fallback-on", f, searchFallbackOnValues); err != nil { + return nil, err + } + } + + nativeOptions, err := parseSearchProviderOptions(providerOptions) + if err != nil { + return nil, err + } + + switch { + case provider != "": + if len(fallbackOn) > 0 { + return nil, fmt.Errorf("--fallback-on has no effect with --provider, which pins a single provider") + } + target, err := buildSearchProviderTarget(provider, nativeOptions[provider]) + if err != nil { + return nil, err + } + pinned := kernel.StrategyPinnedParam{Provider: target} + return &kernel.StrategyUnionParam{OfPinned: &pinned}, nil + + case len(fallbackProviders) > 0: + targets := make([]kernel.ProviderTargetUnionParam, 0, len(fallbackProviders)) + for _, p := range fallbackProviders { + target, err := buildSearchProviderTarget(p, nativeOptions[p]) + if err != nil { + return nil, err + } + targets = append(targets, target) + } + fallback := kernel.StrategyFallbackParam{Providers: targets} + if len(fallbackOn) > 0 { + fallback.FallbackOn = fallbackOn + } + return &kernel.StrategyUnionParam{OfFallback: &fallback}, nil + + case len(nativeOptions) > 0 || len(fallbackOn) > 0: + auto := kernel.StrategyAutoParam{} + if len(fallbackOn) > 0 { + auto.FallbackOn = fallbackOn + } + // Map iteration order is random, so the targets are emitted in the + // documented slug order to keep requests reproducible. + for _, slug := range searchProviderSlugs { + raw, ok := nativeOptions[slug] + if !ok { + continue + } + target, err := buildSearchProviderTarget(slug, raw) + if err != nil { + return nil, err + } + auto.ProviderOptions = append(auto.ProviderOptions, target) + } + return &kernel.StrategyUnionParam{OfAuto: &auto}, nil + } + + return nil, nil +} + +// parseSearchProviderOptions decodes the --provider-options JSON object, which +// maps a provider slug to that provider's native options object. +func parseSearchProviderOptions(raw string) (map[string]json.RawMessage, error) { + raw = strings.TrimSpace(raw) + if raw == "" { + return nil, nil + } + var byProvider map[string]json.RawMessage + if err := json.Unmarshal([]byte(raw), &byProvider); err != nil { + return nil, fmt.Errorf("invalid --provider-options: must be a JSON object keyed by provider slug: %w", err) + } + for slug := range byProvider { + if err := validateSearchEnum("--provider-options key", slug, searchProviderSlugs); err != nil { + return nil, err + } + } + return byProvider, nil +} + +// buildSearchProviderTarget assembles a provider target from a slug and its raw +// native options. The SDK union is discriminated on "provider", so the target is +// round-tripped through JSON rather than switched on by hand. +func buildSearchProviderTarget(slug string, options json.RawMessage) (kernel.ProviderTargetUnionParam, error) { + var target kernel.ProviderTargetUnionParam + + payload := map[string]any{"provider": slug} + if len(options) > 0 { + payload["options"] = options + } + encoded, err := json.Marshal(payload) + if err != nil { + return target, fmt.Errorf("encode provider target for %q: %w", slug, err) + } + if err := target.UnmarshalJSON(encoded); err != nil { + return target, fmt.Errorf("invalid provider options for %q: %w", slug, err) + } + return target, nil +} + +func renderSearch(result *kernel.Search, output string, showContent bool) error { + if result == nil || result.ID == "" { + if output == "json" { + fmt.Println("null") + return nil + } + pterm.Info.Println("No search returned") + return nil + } + + if output == "json" { + return util.PrintPrettyJSON(result) + } + + rows := pterm.TableData{{"Property", "Value"}} + rows = append(rows, []string{"Search ID", result.ID}) + rows = append(rows, []string{"Query", result.Query}) + rows = append(rows, []string{"Provider", result.Provider}) + rows = append(rows, []string{"Results", strconv.Itoa(len(result.Results))}) + rows = append(rows, []string{"Expires At", util.FormatLocal(result.ExpiresAt)}) + PrintTableNoPad(rows, true) + + if result.Answer != "" { + pterm.Println() + pterm.Println("Answer:") + pterm.Println(result.Answer) + } + + if len(result.Results) > 0 { + hasContent := false + for _, r := range result.Results { + if r.Content.Status != "" { + hasContent = true + break + } + } + + header := []string{"#", "Title", "URL", "Source", "Published"} + if hasContent { + header = append(header, "Content") + } + resultRows := pterm.TableData{header} + for _, r := range result.Results { + row := []string{ + strconv.FormatInt(r.Rank, 10), + orSearchDash(r.Title), + r.URL, + orSearchDash(r.Source), + orSearchDash(r.PublishedDate), + } + if hasContent { + row = append(row, orSearchDash(r.Content.Status)) + } + resultRows = append(resultRows, row) + } + pterm.Println() + PrintTableNoPad(resultRows, true) + } else { + pterm.Println() + pterm.Info.Println("No results") + } + + if showContent { + for _, r := range result.Results { + if r.Content.Text == "" { + continue + } + pterm.Println() + pterm.Printf("--- [%d] %s (%s) ---\n", r.Rank, orSearchDash(r.Title), r.URL) + pterm.Println(r.Content.Text) + } + } + + if len(result.Warnings) > 0 { + warnRows := pterm.TableData{{"Warning", "Param", "Provider", "Message"}} + for _, w := range result.Warnings { + warnRows = append(warnRows, []string{w.Code, orSearchDash(w.Param), orSearchDash(w.Provider), w.Message}) + } + pterm.Println() + PrintTableNoPad(warnRows, true) + } + + if len(result.Attempts) > 0 { + attemptRows := pterm.TableData{{"Attempt Provider", "Outcome", "Duration", "Error", "Retryable"}} + for _, a := range result.Attempts { + attemptRows = append(attemptRows, []string{ + a.Provider, + string(a.Outcome), + fmt.Sprintf("%dms", a.DurationMs), + orSearchDash(a.ErrorCode), + formatSearchBool(a.Retryable), + }) + } + pterm.Println() + PrintTableNoPad(attemptRows, true) + } + + usage := fmt.Sprintf("\nUsage: %d result(s), %d content fetch(es)", result.Usage.ResultsCount, result.Usage.ContentFetches) + if result.Usage.Cost > 0 { + usage += fmt.Sprintf(", $%.6f", result.Usage.Cost) + } + pterm.Println(usage) + + return nil +} + +func parseSearchDate(flag, value string) (time.Time, error) { + t, err := time.Parse(searchDateLayout, value) + if err != nil { + return time.Time{}, fmt.Errorf("invalid %s %q: expected YYYY-MM-DD", flag, value) + } + return t, nil +} + +func validateSearchEnum(flag, value string, allowed []string) error { + if value == "" { + return nil + } + for _, a := range allowed { + if value == a { + return nil + } + } + return fmt.Errorf("invalid %s %q: must be one of %s", flag, value, strings.Join(allowed, ", ")) +} + +func orSearchDash(s string) string { + if strings.TrimSpace(s) == "" { + return "-" + } + return s +} + +func formatSearchBool(b bool) string { + if b { + return "yes" + } + return "no" +} + +// --- Cobra wiring --- + +var searchCmd = &cobra.Command{ + Use: "search ", + Short: "Search the web", + Long: "Search the web through Kernel's search providers.\n\n" + + "By default Kernel picks an eligible provider (the auto strategy). Use --provider to pin\n" + + "one provider, or --fallback-providers to try an ordered chain. Portable filters that a\n" + + "provider cannot honor are approximated or dropped, and the outcome is reported as a\n" + + "warning unless --strict-params is set.\n\n" + + "Results are retained for 24 hours and can be re-read with `kernel search get `.", + Example: ` kernel search "kernel browser automation" + kernel search "latest go release" --recency week --max-results 5 + kernel search "site news" --include-domains example.com --content --show-content + kernel search "ai research" --provider exa --provider-options '{"exa":{"type":"neural"}}'`, + Args: cobra.ArbitraryArgs, + RunE: runSearchQuery, +} + +var searchGetCmd = &cobra.Command{ + Use: "get ", + Short: "Get a retained search by ID", + Long: "Return a retained search exactly as it was returned by `kernel search`: results, attempts,\n" + + "warnings, and usage. No provider is called and nothing is billed. Searches expire 24 hours\n" + + "after completion.", + Args: cobra.ExactArgs(1), + RunE: runSearchGet, +} + +var searchProvidersCmd = &cobra.Command{ + Use: "providers", + Short: "List search providers and their capabilities", + Long: "List providers, their result caps, content-retrieval capabilities, and the OpenAPI\n" + + "component backing their native options. Pass --slug to inspect a single provider, which\n" + + "also prints its portable-parameter support matrix and notes.", + Args: cobra.NoArgs, + RunE: runSearchProviders, +} + +var searchContentsCmd = &cobra.Command{ + Use: "contents ", + Short: "Fetch content for results of a retained search", + Long: "Deferred result-content retrieval for a retained search. This endpoint is reserved and\n" + + "returns 404 until the retrieval implementation ships; use `kernel search --content` for\n" + + "inline retrieval in the meantime.", + Args: cobra.ExactArgs(1), + RunE: runSearchContents, +} + +// addSearchContentFlags registers the portable content-retrieval options shared +// by `kernel search` and `kernel search contents`. +func addSearchContentFlags(cmd *cobra.Command) { + cmd.Flags().String("content-source", "", "Content retrieval source: auto, provider, or browser") + cmd.Flags().String("content-format", "", "Extracted content format: markdown or text") + cmd.Flags().Int64("content-max-chars", 0, "Per-result Unicode character limit after extraction") + cmd.Flags().Int64("content-max-age-hours", 0, "Maximum acceptable age of cached page content; 0 forces a live fetch") + cmd.Flags().Int64("content-timeout-ms", 0, "Per-result retrieval deadline in milliseconds") + cmd.Flags().String("content-browser-id", "", "Existing browser session to retrieve content through (requires --content-source browser)") + cmd.Flags().String("content-browser-mode", "", "Browser retrieval mode: curl or render") +} + +func searchContentFlags(cmd *cobra.Command, enabled bool) searchContentInput { + source, _ := cmd.Flags().GetString("content-source") + format, _ := cmd.Flags().GetString("content-format") + maxChars, _ := cmd.Flags().GetInt64("content-max-chars") + timeoutMs, _ := cmd.Flags().GetInt64("content-timeout-ms") + browserID, _ := cmd.Flags().GetString("content-browser-id") + browserMode, _ := cmd.Flags().GetString("content-browser-mode") + + in := searchContentInput{ + Enabled: enabled, + Source: source, + Format: format, + MaxChars: maxChars, + TimeoutMs: timeoutMs, + BrowserID: browserID, + BrowserMode: browserMode, + } + // 0 is a meaningful max age, so it is only sent when explicitly supplied. + if cmd.Flags().Changed("content-max-age-hours") { + maxAge, _ := cmd.Flags().GetInt64("content-max-age-hours") + in.MaxAgeHours = &maxAge + } + return in +} + +func init() { + searchCmd.AddCommand(searchGetCmd) + searchCmd.AddCommand(searchProvidersCmd) + searchCmd.AddCommand(searchContentsCmd) + + addJSONOutputFlag(searchCmd) + searchCmd.Flags().String("country", "", "ISO 3166-1 alpha-2 search locale preference") + searchCmd.Flags().String("language", "", "BCP 47 search language preference") + searchCmd.Flags().Int64("max-results", 0, "Requested result count, 1 through 100 (clamped to the provider cap)") + searchCmd.Flags().String("recency", "", "Relative search window: hour, day, week, month, or year") + searchCmd.Flags().String("safe-search", "", "Safety preference: off, moderate, or strict") + searchCmd.Flags().String("start-date", "", "Inclusive publication-date lower bound (YYYY-MM-DD)") + searchCmd.Flags().String("end-date", "", "Inclusive publication-date upper bound (YYYY-MM-DD)") + searchCmd.Flags().StringSlice("include-domains", nil, "Hostnames (and subdomains) to prefer") + searchCmd.Flags().StringSlice("exclude-domains", nil, "Hostnames (and subdomains) to exclude") + searchCmd.Flags().Bool("strict-params", false, "Require every supplied portable parameter to be honored exactly") + searchCmd.Flags().Bool("include-raw", false, "Include untouched provider payloads in raw fields") + searchCmd.Flags().Int64("timeout-ms", 0, "Overall deadline across search attempts and inline retrieval") + searchCmd.Flags().Bool("content", false, "Retrieve page content for each result using portable defaults") + searchCmd.Flags().Bool("show-content", false, "Print the extracted content text for each result") + addSearchContentFlags(searchCmd) + searchCmd.Flags().String("provider", "", "Pin a single provider: "+strings.Join(searchProviderSlugs, ", ")) + searchCmd.Flags().StringSlice("fallback-providers", nil, "Ordered provider chain to try in turn") + searchCmd.Flags().StringSlice("fallback-on", nil, "Outcomes that advance to the next provider: error, timeout, empty") + searchCmd.Flags().String("provider-options", "", searchProviderOptsUsage) + + addJSONOutputFlag(searchGetCmd) + searchGetCmd.Flags().Bool("show-content", false, "Print the extracted content text for each result") + + addJSONOutputFlag(searchProvidersCmd) + searchProvidersCmd.Flags().String("slug", "", "Filter to a single provider: "+strings.Join(searchProviderSlugs, ", ")) + + addJSONOutputFlag(searchContentsCmd) + searchContentsCmd.Flags().StringSlice("result-ids", nil, "Result IDs from the retained search, in the desired response order") + searchContentsCmd.Flags().Int64("limit", 0, "Number of results to fetch starting from rank 1 (mutually exclusive with --result-ids)") + searchContentsCmd.Flags().Int64("timeout-ms", 0, "Overall deadline across all selected results") + addSearchContentFlags(searchContentsCmd) +} + +func newSearchCmd(cmd *cobra.Command) SearchCmd { + client := getKernelClient(cmd) + svc := client.Search + return SearchCmd{search: &svc, providers: &svc.Providers, contents: &svc.Contents} +} + +func runSearchQuery(cmd *cobra.Command, args []string) error { + if len(args) == 0 { + return cmd.Help() + } + + output, _ := cmd.Flags().GetString("output") + country, _ := cmd.Flags().GetString("country") + language, _ := cmd.Flags().GetString("language") + maxResults, _ := cmd.Flags().GetInt64("max-results") + recency, _ := cmd.Flags().GetString("recency") + safeSearch, _ := cmd.Flags().GetString("safe-search") + startDate, _ := cmd.Flags().GetString("start-date") + endDate, _ := cmd.Flags().GetString("end-date") + includeDomains, _ := cmd.Flags().GetStringSlice("include-domains") + excludeDomains, _ := cmd.Flags().GetStringSlice("exclude-domains") + strictParams, _ := cmd.Flags().GetBool("strict-params") + includeRaw, _ := cmd.Flags().GetBool("include-raw") + timeoutMs, _ := cmd.Flags().GetInt64("timeout-ms") + content, _ := cmd.Flags().GetBool("content") + showContent, _ := cmd.Flags().GetBool("show-content") + provider, _ := cmd.Flags().GetString("provider") + fallbackProviders, _ := cmd.Flags().GetStringSlice("fallback-providers") + fallbackOn, _ := cmd.Flags().GetStringSlice("fallback-on") + providerOptions, _ := cmd.Flags().GetString("provider-options") + + // --show-content is only useful alongside retrieval, so it implies --content. + contentIn := searchContentFlags(cmd, content || showContent) + + return newSearchCmd(cmd).Query(cmd.Context(), SearchQueryInput{ + Query: strings.Join(args, " "), + Output: output, + Country: country, + Language: language, + MaxResults: maxResults, + Recency: recency, + SafeSearch: safeSearch, + StartDate: startDate, + EndDate: endDate, + IncludeDomains: includeDomains, + ExcludeDomains: excludeDomains, + StrictParams: strictParams, + IncludeRaw: includeRaw, + TimeoutMs: timeoutMs, + ShowContent: showContent, + Content: contentIn, + Provider: provider, + FallbackProviders: fallbackProviders, + FallbackOn: fallbackOn, + ProviderOptions: providerOptions, + }) +} + +func runSearchGet(cmd *cobra.Command, args []string) error { + output, _ := cmd.Flags().GetString("output") + showContent, _ := cmd.Flags().GetBool("show-content") + return newSearchCmd(cmd).Get(cmd.Context(), SearchGetInput{ + ID: args[0], + Output: output, + ShowContent: showContent, + }) +} + +func runSearchProviders(cmd *cobra.Command, args []string) error { + output, _ := cmd.Flags().GetString("output") + slug, _ := cmd.Flags().GetString("slug") + return newSearchCmd(cmd).Providers(cmd.Context(), SearchProvidersInput{Slug: slug, Output: output}) +} + +func runSearchContents(cmd *cobra.Command, args []string) error { + output, _ := cmd.Flags().GetString("output") + resultIDs, _ := cmd.Flags().GetStringSlice("result-ids") + limit, _ := cmd.Flags().GetInt64("limit") + timeoutMs, _ := cmd.Flags().GetInt64("timeout-ms") + + return newSearchCmd(cmd).Contents(cmd.Context(), SearchContentsInput{ + ID: args[0], + Output: output, + ResultIDs: resultIDs, + Limit: limit, + TimeoutMs: timeoutMs, + Content: searchContentFlags(cmd, true), + }) +} diff --git a/cmd/search_test.go b/cmd/search_test.go new file mode 100644 index 00000000..fc484948 --- /dev/null +++ b/cmd/search_test.go @@ -0,0 +1,414 @@ +package cmd + +import ( + "context" + "encoding/json" + "strings" + "testing" + "time" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// FakeSearchService implements SearchService. +type FakeSearchService struct { + NewFunc func(ctx context.Context, body kernel.SearchNewParams, opts ...option.RequestOption) (*kernel.Search, error) + GetFunc func(ctx context.Context, id string, opts ...option.RequestOption) (*kernel.Search, error) + LastBody kernel.SearchNewParams +} + +func (f *FakeSearchService) New(ctx context.Context, body kernel.SearchNewParams, opts ...option.RequestOption) (*kernel.Search, error) { + f.LastBody = body + if f.NewFunc != nil { + return f.NewFunc(ctx, body, opts...) + } + return &kernel.Search{ID: "srch_1", Query: body.Request.Query, Provider: "brave", ExpiresAt: time.Unix(0, 0)}, nil +} + +func (f *FakeSearchService) Get(ctx context.Context, id string, opts ...option.RequestOption) (*kernel.Search, error) { + if f.GetFunc != nil { + return f.GetFunc(ctx, id, opts...) + } + return &kernel.Search{ID: id, Query: "cached", Provider: "brave", ExpiresAt: time.Unix(0, 0)}, nil +} + +// FakeSearchProvidersService implements SearchProvidersService. +type FakeSearchProvidersService struct { + ListFunc func(ctx context.Context, query kernel.SearchProviderListParams, opts ...option.RequestOption) (*[]kernel.Provider, error) + LastQuery kernel.SearchProviderListParams +} + +func (f *FakeSearchProvidersService) List(ctx context.Context, query kernel.SearchProviderListParams, opts ...option.RequestOption) (*[]kernel.Provider, error) { + f.LastQuery = query + if f.ListFunc != nil { + return f.ListFunc(ctx, query, opts...) + } + items := []kernel.Provider{{Slug: "brave", MaxResultsCap: 20}} + return &items, nil +} + +// FakeSearchContentsService implements SearchContentsService. +type FakeSearchContentsService struct { + FetchFunc func(ctx context.Context, id string, body kernel.SearchContentFetchParams, opts ...option.RequestOption) error + LastID string + LastBody kernel.SearchContentFetchParams +} + +func (f *FakeSearchContentsService) Fetch(ctx context.Context, id string, body kernel.SearchContentFetchParams, opts ...option.RequestOption) error { + f.LastID = id + f.LastBody = body + if f.FetchFunc != nil { + return f.FetchFunc(ctx, id, body, opts...) + } + return nil +} + +// requestJSON marshals the captured request so tests can assert on the exact +// wire payload, which is where the union and strategy encoding actually matters. +func requestJSON(t *testing.T, params kernel.SearchNewParams) map[string]any { + t.Helper() + raw, err := json.Marshal(params) + require.NoError(t, err) + var out map[string]any + require.NoError(t, json.Unmarshal(raw, &out)) + return out +} + +func TestSearchQueryBuildsPortableParams(t *testing.T) { + _ = capturePtermOutput(t) + fake := &FakeSearchService{} + s := SearchCmd{search: fake} + + err := s.Query(context.Background(), SearchQueryInput{ + Query: "kernel browsers", + Country: "US", + Language: "en", + MaxResults: 5, + Recency: "week", + SafeSearch: "moderate", + StartDate: "2026-01-02", + EndDate: "2026-02-03", + IncludeDomains: []string{"example.com"}, + ExcludeDomains: []string{"spam.example"}, + StrictParams: true, + IncludeRaw: true, + TimeoutMs: 15000, + }) + require.NoError(t, err) + + body := requestJSON(t, fake.LastBody) + assert.Equal(t, "kernel browsers", body["query"]) + assert.Equal(t, "US", body["country"]) + assert.Equal(t, "en", body["language"]) + assert.EqualValues(t, 5, body["max_results"]) + assert.Equal(t, "week", body["recency"]) + assert.Equal(t, "moderate", body["safe_search"]) + assert.Equal(t, "2026-01-02", body["start_date"]) + assert.Equal(t, "2026-02-03", body["end_date"]) + assert.Equal(t, []any{"example.com"}, body["include_domains"]) + assert.Equal(t, []any{"spam.example"}, body["exclude_domains"]) + assert.Equal(t, true, body["strict_params"]) + assert.Equal(t, true, body["include_raw"]) + assert.EqualValues(t, 15000, body["timeout_ms"]) + // No strategy flags were supplied, so the API applies its auto default. + assert.NotContains(t, body, "strategy") +} + +func TestSearchQueryContentBooleanShorthand(t *testing.T) { + _ = capturePtermOutput(t) + fake := &FakeSearchService{} + s := SearchCmd{search: fake} + + require.NoError(t, s.Query(context.Background(), SearchQueryInput{ + Query: "q", + Content: searchContentInput{Enabled: true}, + })) + + body := requestJSON(t, fake.LastBody) + assert.Equal(t, true, body["content"]) +} + +func TestSearchQueryContentOptionsObject(t *testing.T) { + _ = capturePtermOutput(t) + fake := &FakeSearchService{} + s := SearchCmd{search: fake} + + maxAge := int64(0) + require.NoError(t, s.Query(context.Background(), SearchQueryInput{ + Query: "q", + Content: searchContentInput{ + Enabled: true, + Source: "browser", + Format: "text", + MaxChars: 2000, + MaxAgeHours: &maxAge, + TimeoutMs: 9000, + BrowserID: "br_123", + BrowserMode: "render", + }, + })) + + body := requestJSON(t, fake.LastBody) + content, ok := body["content"].(map[string]any) + require.True(t, ok, "content should be an options object, got %#v", body["content"]) + assert.Equal(t, "browser", content["source"]) + assert.Equal(t, "text", content["format"]) + assert.EqualValues(t, 2000, content["max_chars"]) + // 0 is meaningful: it forces a live fetch, so it must survive to the wire. + assert.EqualValues(t, 0, content["max_age_hours"]) + assert.EqualValues(t, 9000, content["timeout_ms"]) + assert.Equal(t, map[string]any{"browser_id": "br_123", "mode": "render"}, content["browser"]) +} + +func TestSearchQueryPinnedStrategyWithNativeOptions(t *testing.T) { + _ = capturePtermOutput(t) + fake := &FakeSearchService{} + s := SearchCmd{search: fake} + + require.NoError(t, s.Query(context.Background(), SearchQueryInput{ + Query: "q", + Provider: "tavily", + ProviderOptions: `{"tavily":{"include_answer":true}}`, + })) + + body := requestJSON(t, fake.LastBody) + strategy, ok := body["strategy"].(map[string]any) + require.True(t, ok) + assert.Equal(t, "pinned", strategy["type"]) + provider, ok := strategy["provider"].(map[string]any) + require.True(t, ok) + assert.Equal(t, "tavily", provider["provider"]) + assert.Equal(t, map[string]any{"include_answer": true}, provider["options"]) +} + +func TestSearchQueryFallbackStrategyPreservesOrder(t *testing.T) { + _ = capturePtermOutput(t) + fake := &FakeSearchService{} + s := SearchCmd{search: fake} + + require.NoError(t, s.Query(context.Background(), SearchQueryInput{ + Query: "q", + FallbackProviders: []string{"exa", "brave"}, + FallbackOn: []string{"error", "empty"}, + })) + + body := requestJSON(t, fake.LastBody) + strategy, ok := body["strategy"].(map[string]any) + require.True(t, ok) + assert.Equal(t, "fallback", strategy["type"]) + assert.Equal(t, []any{"error", "empty"}, strategy["fallback_on"]) + providers, ok := strategy["providers"].([]any) + require.True(t, ok) + require.Len(t, providers, 2) + assert.Equal(t, "exa", providers[0].(map[string]any)["provider"]) + assert.Equal(t, "brave", providers[1].(map[string]any)["provider"]) +} + +func TestSearchQueryAutoStrategyFromProviderOptions(t *testing.T) { + _ = capturePtermOutput(t) + fake := &FakeSearchService{} + s := SearchCmd{search: fake} + + require.NoError(t, s.Query(context.Background(), SearchQueryInput{ + Query: "q", + FallbackOn: []string{"timeout"}, + ProviderOptions: `{"brave":{"safesearch":"strict"},"exa":{}}`, + })) + + body := requestJSON(t, fake.LastBody) + strategy, ok := body["strategy"].(map[string]any) + require.True(t, ok) + assert.Equal(t, "auto", strategy["type"]) + assert.Equal(t, []any{"timeout"}, strategy["fallback_on"]) + opts, ok := strategy["provider_options"].([]any) + require.True(t, ok) + require.Len(t, opts, 2) + // Emitted in documented slug order rather than map order. + assert.Equal(t, "brave", opts[0].(map[string]any)["provider"]) + assert.Equal(t, "exa", opts[1].(map[string]any)["provider"]) +} + +func TestSearchQueryValidationErrors(t *testing.T) { + _ = capturePtermOutput(t) + s := SearchCmd{search: &FakeSearchService{}} + + cases := []struct { + name string + in SearchQueryInput + wantErr string + }{ + {"empty query", SearchQueryInput{Query: " "}, "a search query is required"}, + {"bad recency", SearchQueryInput{Query: "q", Recency: "decade"}, "invalid --recency"}, + {"bad safe search", SearchQueryInput{Query: "q", SafeSearch: "maybe"}, "invalid --safe-search"}, + {"max results too high", SearchQueryInput{Query: "q", MaxResults: 101}, "--max-results must be between 1 and 100"}, + {"bad start date", SearchQueryInput{Query: "q", StartDate: "01-02-2026"}, "invalid --start-date"}, + {"bad content source", SearchQueryInput{Query: "q", Content: searchContentInput{Source: "psychic"}}, "invalid --content-source"}, + {"browser id with provider source", SearchQueryInput{Query: "q", Content: searchContentInput{Source: "provider", BrowserID: "br_1"}}, "--content-browser-id requires --content-source browser"}, + {"bad provider", SearchQueryInput{Query: "q", Provider: "askjeeves"}, "invalid --provider"}, + {"provider with fallback chain", SearchQueryInput{Query: "q", Provider: "brave", FallbackProviders: []string{"exa"}}, "mutually exclusive"}, + {"fallback-on with pinned provider", SearchQueryInput{Query: "q", Provider: "brave", FallbackOn: []string{"error"}}, "--fallback-on has no effect with --provider"}, + {"bad fallback-on", SearchQueryInput{Query: "q", FallbackProviders: []string{"exa"}, FallbackOn: []string{"sometimes"}}, "invalid --fallback-on"}, + {"malformed provider options", SearchQueryInput{Query: "q", ProviderOptions: "not json"}, "invalid --provider-options"}, + {"unknown provider options key", SearchQueryInput{Query: "q", ProviderOptions: `{"altavista":{}}`}, "invalid --provider-options key"}, + } + + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + err := s.Query(context.Background(), tc.in) + require.Error(t, err) + assert.Contains(t, err.Error(), tc.wantErr) + }) + } +} + +func TestSearchQueryRendersResults(t *testing.T) { + buf := capturePtermOutput(t) + fake := &FakeSearchService{ + NewFunc: func(ctx context.Context, body kernel.SearchNewParams, opts ...option.RequestOption) (*kernel.Search, error) { + return &kernel.Search{ + ID: "srch_abc", + Query: body.Request.Query, + Provider: "brave", + Answer: "42", + ExpiresAt: time.Unix(0, 0), + Results: []kernel.Result{{ + ID: "res_1", + Rank: 1, + URL: "https://example.com/a", + Title: "Example A", + Source: "example.com", + Content: kernel.ResultContent{Status: "ok", Text: "extracted body"}, + }}, + Warnings: []kernel.Warning{{Code: "max_results_clamped", Message: "clamped to 20"}}, + Attempts: []kernel.Attempt{{Provider: "brave", Outcome: "success", DurationMs: 120}}, + Usage: kernel.Usage{ResultsCount: 1, ContentFetches: 1}, + }, nil + }, + } + s := SearchCmd{search: fake} + + require.NoError(t, s.Query(context.Background(), SearchQueryInput{Query: "q", ShowContent: true})) + + out := buf.String() + assert.Contains(t, out, "srch_abc") + assert.Contains(t, out, "Example A") + assert.Contains(t, out, "https://example.com/a") + assert.Contains(t, out, "42") + assert.Contains(t, out, "extracted body") + assert.Contains(t, out, "max_results_clamped") + assert.Contains(t, out, "success") + assert.Contains(t, out, "Usage: 1 result(s), 1 content fetch(es)") +} + +func TestSearchGetRendersRetainedSearch(t *testing.T) { + buf := capturePtermOutput(t) + s := SearchCmd{search: &FakeSearchService{}} + + require.NoError(t, s.Get(context.Background(), SearchGetInput{ID: "srch_xyz"})) + assert.Contains(t, buf.String(), "srch_xyz") +} + +func TestSearchProvidersFiltersBySlugAndPrintsDetail(t *testing.T) { + buf := capturePtermOutput(t) + fake := &FakeSearchProvidersService{ + ListFunc: func(ctx context.Context, query kernel.SearchProviderListParams, opts ...option.RequestOption) (*[]kernel.Provider, error) { + items := []kernel.Provider{{ + Slug: "exa", + MaxResultsCap: 25, + Content: kernel.ProviderContent{Inline: true, PostHoc: false, FreshnessControl: true}, + ProviderOptions: kernel.ProviderProviderOptions{SchemaRef: "ExaOptions"}, + Params: kernel.ProviderParams{Recency: kernel.ProviderParamsRecency{Support: "emulated", Notes: "widened to days"}}, + Notes: []string{"neural search is slower"}, + }} + return &items, nil + }, + } + s := SearchCmd{providers: fake} + + require.NoError(t, s.Providers(context.Background(), SearchProvidersInput{Slug: "exa"})) + + assert.Equal(t, kernel.SearchProviderListParamsSlugExa, fake.LastQuery.Slug) + out := buf.String() + assert.Contains(t, out, "exa") + assert.Contains(t, out, "25") + assert.Contains(t, out, "ExaOptions") + assert.Contains(t, out, "emulated") + assert.Contains(t, out, "neural search is slower") +} + +func TestSearchProvidersRejectsUnknownSlug(t *testing.T) { + _ = capturePtermOutput(t) + s := SearchCmd{providers: &FakeSearchProvidersService{}} + err := s.Providers(context.Background(), SearchProvidersInput{Slug: "altavista"}) + require.Error(t, err) + assert.Contains(t, err.Error(), "invalid --slug") +} + +func TestSearchProvidersEmptyJSON(t *testing.T) { + _ = capturePtermOutput(t) + fake := &FakeSearchProvidersService{ + ListFunc: func(ctx context.Context, query kernel.SearchProviderListParams, opts ...option.RequestOption) (*[]kernel.Provider, error) { + items := []kernel.Provider{} + return &items, nil + }, + } + s := SearchCmd{providers: fake} + require.NoError(t, s.Providers(context.Background(), SearchProvidersInput{Output: "json"})) +} + +func TestSearchContentsBuildsFetchRequest(t *testing.T) { + _ = capturePtermOutput(t) + fake := &FakeSearchContentsService{} + s := SearchCmd{contents: fake} + + require.NoError(t, s.Contents(context.Background(), SearchContentsInput{ + ID: "srch_abc", + ResultIDs: []string{"res_2", "res_1"}, + TimeoutMs: 5000, + Content: searchContentInput{Source: "auto", Format: "markdown", MaxChars: 500}, + })) + + assert.Equal(t, "srch_abc", fake.LastID) + raw, err := json.Marshal(fake.LastBody) + require.NoError(t, err) + var body map[string]any + require.NoError(t, json.Unmarshal(raw, &body)) + assert.Equal(t, []any{"res_2", "res_1"}, body["result_ids"]) + assert.EqualValues(t, 5000, body["timeout_ms"]) + assert.Equal(t, map[string]any{"source": "auto", "format": "markdown", "max_chars": float64(500)}, body["content"]) + assert.NotContains(t, body, "limit") +} + +func TestSearchContentsRejectsResultIDsWithLimit(t *testing.T) { + _ = capturePtermOutput(t) + s := SearchCmd{contents: &FakeSearchContentsService{}} + err := s.Contents(context.Background(), SearchContentsInput{ID: "srch_abc", ResultIDs: []string{"res_1"}, Limit: 5}) + require.Error(t, err) + assert.Contains(t, err.Error(), "mutually exclusive") +} + +func TestSearchCommandFlagsAreWired(t *testing.T) { + for _, name := range []string{ + "country", "language", "max-results", "recency", "safe-search", "start-date", "end-date", + "include-domains", "exclude-domains", "strict-params", "include-raw", "timeout-ms", + "content", "content-source", "content-format", "content-max-chars", "content-max-age-hours", + "content-timeout-ms", "content-browser-id", "content-browser-mode", "show-content", + "provider", "fallback-providers", "fallback-on", "provider-options", "output", + } { + assert.NotNil(t, searchCmd.Flags().Lookup(name), "kernel search is missing --%s", name) + } + for _, name := range []string{"result-ids", "limit", "timeout-ms", "content-source", "output"} { + assert.NotNil(t, searchContentsCmd.Flags().Lookup(name), "kernel search contents is missing --%s", name) + } + assert.NotNil(t, searchProvidersCmd.Flags().Lookup("slug")) + assert.NotNil(t, searchGetCmd.Flags().Lookup("show-content")) + + var names []string + for _, c := range searchCmd.Commands() { + names = append(names, c.Name()) + } + assert.ElementsMatch(t, []string{"get", "providers", "contents"}, names, "got %s", strings.Join(names, ",")) +} diff --git a/cmd/vaults_commands.go b/cmd/vaults_commands.go index d725e66c..95518a87 100644 --- a/cmd/vaults_commands.go +++ b/cmd/vaults_commands.go @@ -177,11 +177,13 @@ and corrective guidance; no fields were written by that request. Inspect and cor the cause before deciding on a new fill. Transport loss remains an uncertain outcome. prepare_checkout requires checkout.browser_id, checkout.merchant_origin (canonical HTTPS origin of the top-level merchant page, not a processor iframe), and checkout.environment -(production, sandbox, or shared). Optional checkout.psp selects the tokenization processor: -square, braintree, worldpay, bambora, or mercado_pago. Omit psp for Square; non-Square +(production, sandbox, or shared). Optional checkout.psp selects the checkout processor: +square, braintree, worldpay, bambora, mercado_pago, or adyen. Omit psp for Square; non-Square processors require multi-processor preparation enablement. Use production or sandbox for -square, braintree and worldpay; shared for bambora and mercado_pago. Shared endpoints do not -establish test mode; merchant credentials determine it. +square, braintree, worldpay and adyen; shared for bambora and mercado_pago. Shared endpoints do +not establish test mode; merchant credentials determine it. adyen prepares fresh-card Sessions +requests on Adyen hosts only: fill public dummy card fields, not vault aliases. Adyen device +approval and browser Authorised responses are not capture or fulfillment evidence. Use only when advertised for an AgentCard card. Keep the returned approval page open, poll until ready_to_submit, then submit native Pay before preparation.expires_at. Preparations are single-use, including after failure or expiry; never retry automatically. diff --git a/cmd/vaults_credentials.go b/cmd/vaults_credentials.go index 03b697c8..5d20dca9 100644 --- a/cmd/vaults_credentials.go +++ b/cmd/vaults_credentials.go @@ -1,6 +1,7 @@ package cmd import ( + "bytes" "context" "encoding/json" "fmt" @@ -63,7 +64,7 @@ func newVaultCredentialsCommand() *cobra.Command { }, } if update { - cmd.Long += "\nUpdate preserves omitted fields, replaces nonempty string values, and clears supported values with null or an empty string. Clearing a required text/email/password field returns pending_collection; form submissions still require a nonempty value.\nField definitions are immutable. Do not automatically retry version conflicts." + cmd.Long += "\nUpdate spec fields are an object keyed by field name, not the ordered array used on create.\nUpdate preserves omitted fields, replaces nonempty string values, and clears supported values with null or an empty string. Clearing a required text/email/password field returns pending_collection; form submissions still require a nonempty value.\nField definitions are immutable. Do not automatically retry version conflicts." cmd.Flags().Int64("version", 0, "Expected version from items get (required; never auto-refreshed)") _ = cmd.MarkFlagRequired("version") cmd.Flags().String("expected-item-id", "", "Immutable item ID from the original read; reject an update if the key now refers to a replacement item") @@ -127,8 +128,17 @@ func (c VaultsCmd) saveCredential(ctx context.Context, vault, key string, data [ } else { var spec kernel.CredentialVaultItemSpecInputParam if json.Unmarshal(data, &spec) != nil || len(spec.Fields) == 0 { + if credentialSpecUsesKeyedFields(data) { + return fmt.Errorf("credential spec fields must be an ordered array of definitions carrying a name, not an object keyed by name") + } return fmt.Errorf("credential spec requires fields") } + // Names key values, updates, and fills; reject specs the form cannot address. + for _, field := range spec.Fields { + if strings.TrimSpace(field.Name) == "" { + return fmt.Errorf("every credential spec field requires a name") + } + } item, err = c.vaults.Items.Upsert(ctx, key, kernel.VaultItemUpsertParams{IDOrName: vault, OfCredential: &kernel.CredentialVaultItemRequestParam{Type: "credential", Spec: spec}}, option.WithMaxRetries(0)) } if err != nil { @@ -136,3 +146,16 @@ func (c VaultsCmd) saveCredential(ctx context.Context, vault, key string, data [ } return c.showItem(item, output, open) } + +// The create spec moved from fields keyed by name to an ordered array; point +// callers still sending the object form at the replacement shape. +func credentialSpecUsesKeyedFields(data []byte) bool { + var object struct { + Fields json.RawMessage `json:"fields"` + } + if json.Unmarshal(data, &object) != nil { + return false + } + fields := bytes.TrimSpace(object.Fields) + return len(fields) > 0 && fields[0] == '{' +} diff --git a/cmd/vaults_fill_credentials_test.go b/cmd/vaults_fill_credentials_test.go index c351e70c..29d7b7f6 100644 --- a/cmd/vaults_fill_credentials_test.go +++ b/cmd/vaults_fill_credentials_test.go @@ -19,7 +19,7 @@ func TestVaultFillBothItemTypesAndInputs(t *testing.T) { for _, input := range []string{"params", "spec-file"} { for _, test := range []struct{ name, item, params, result string }{ {"card", readyFillCardFixture, fillParamsFixture, completedFillFixture}, - {"credential", readyFillCredentialFixture, `{"browser_id":"browser-id","fields":[{"field":"expiration","selector":"#password"},{"field":"custom field","selector":"#custom"},{"field":"otp","selector":"#code"}]}`, completedFillFixture}, + {"credential", readyFillCredentialFixture, `{"browser_id":"browser-id","fields":[{"field":"expiration","selector":"#password"},{"field":"custom_field","selector":"#custom"},{"field":"otp","selector":"#code"}]}`, completedFillFixture}, {"credential URL", readyFillCredentialFixture, `{"browser_id":"browser-id","page_url":"http://localhost/login","fields":[{"field":"expiration","selector":"#password"}]}`, `{"type":"fill","status":"completed","fields":[{"index":0,"status":"filled"}]}`}, } { t.Run(input+"/"+test.name, func(t *testing.T) { @@ -56,7 +56,7 @@ func TestVaultCredentialFillValidation(t *testing.T) { for _, params := range []string{ `{"browser_id":"id","fields":[{"field":"unknown","selector":"#field"}]}`, `{"browser_id":"id","fields":[{"field":"expiration","selector":"#field","format":"MM/YY"}]}`, - `{"browser_id":"id","fields":[{"field":"custom field","selector":"#field","format":"MM/YYYY"}]}`, + `{"browser_id":"id","fields":[{"field":"custom_field","selector":"#field","format":"MM/YYYY"}]}`, `{"browser_id":"id","fields":[{"field":"expiration","selector":"#field","value":"secret-sentinel"}]}`, `{"browser_id":"id","browser_id":"secret-sentinel","fields":[{"field":"expiration","selector":"#field"}]}`, } { @@ -106,7 +106,7 @@ func TestCredentialFillCLIOutcomes(t *testing.T) { io.WriteString(w, result) })) defer server.Close() - out, stderr, exit := runVaultFillCLI(t, server.URL, "fill", "--params", `{"browser_id":"id","fields":[{"field":"expiration","selector":"#password"},{"field":"custom field","selector":"#custom"},{"field":"otp","selector":"#code"}]}`, "-o", "json") + out, stderr, exit := runVaultFillCLI(t, server.URL, "fill", "--params", `{"browser_id":"id","fields":[{"field":"expiration","selector":"#password"},{"field":"custom_field","selector":"#custom"},{"field":"otp","selector":"#code"}]}`, "-o", "json") assert.True(t, json.Valid([]byte(out))) assert.JSONEq(t, result, out) assert.Empty(t, stderr) diff --git a/cmd/vaults_help.go b/cmd/vaults_help.go index 8e3dc275..e9b38ab7 100644 --- a/cmd/vaults_help.go +++ b/cmd/vaults_help.go @@ -69,7 +69,7 @@ type AgentCardCardSpec = { merchant: string; // approval-screen name; 1..120 characters amount: number; // integer minor units; 1..9007199254740991 currency: string; // three letters - card_id?: string; // vc_...; otherwise chosen at approval + card_id?: string; // opaque AgentCard ID, pass through unchanged; else chosen at approval }; type LinkLineItem = { diff --git a/cmd/vaults_prepare_checkout.go b/cmd/vaults_prepare_checkout.go index b58ca4d8..74967c6e 100644 --- a/cmd/vaults_prepare_checkout.go +++ b/cmd/vaults_prepare_checkout.go @@ -10,9 +10,9 @@ import ( kernel "github.com/kernel/kernel-go-sdk" ) -// Environments and tokenization processors accepted by prepare_checkout. Square, -// Braintree and Worldpay use production or sandbox; Bambora and Mercado Pago use -// shared. Pairing is enforced by the API, which owns processor enablement. +// Environments and checkout processors accepted by prepare_checkout. Square, +// Braintree, Worldpay and Adyen use production or sandbox; Bambora and Mercado Pago +// use shared. Pairing is enforced by the API, which owns processor enablement. var vaultCheckoutEnvironments = []kernel.VaultCheckoutContextEnvironment{ kernel.VaultCheckoutContextEnvironmentProduction, kernel.VaultCheckoutContextEnvironmentSandbox, @@ -25,6 +25,7 @@ var vaultCheckoutProcessors = []kernel.AgentcardPreparedProcessor{ kernel.AgentcardPreparedProcessorWorldpay, kernel.AgentcardPreparedProcessorBambora, kernel.AgentcardPreparedProcessorMercadoPago, + kernel.AgentcardPreparedProcessorAdyen, } func vaultCheckoutProcessorNames() []string { diff --git a/cmd/vaults_prepare_checkout_test.go b/cmd/vaults_prepare_checkout_test.go index 5cb43950..cadecc72 100644 --- a/cmd/vaults_prepare_checkout_test.go +++ b/cmd/vaults_prepare_checkout_test.go @@ -108,7 +108,7 @@ func TestVaultPrepareCheckoutInvalidParams(t *testing.T) { } _, err := parseVaultCheckoutParams(strings.Replace(checkoutParamsFixture, "https://shop.example", "http://localhost:3000", 1)) require.NoError(t, err) - for _, psp := range []string{"square", "braintree", "worldpay", "bambora", "mercado_pago"} { + for _, psp := range []string{"square", "braintree", "worldpay", "bambora", "mercado_pago", "adyen"} { params, err := parseVaultCheckoutParams(strings.Replace(checkoutParamsFixture, `"environment":`, `"psp":"`+psp+`","environment":`, 1)) require.NoError(t, err, psp) assert.Equal(t, psp, string(params.Psp)) diff --git a/cmd/vaults_public_values_test.go b/cmd/vaults_public_values_test.go index b88bc680..ca6b98c6 100644 --- a/cmd/vaults_public_values_test.go +++ b/cmd/vaults_public_values_test.go @@ -121,3 +121,41 @@ func TestVaultFillActionableErrors(t *testing.T) { }) } } + +// label is non-secret display metadata: it must reach the API unchanged on create +// and survive the display-safe output projection on every read. +func TestVaultCredentialLabelsRoundTrip(t *testing.T) { + t.Setenv("KERNEL_PROJECT", "") + spec := `{"description":"Hacker News","fields":[{"name":"username","label":"Username or email","type":"text","required":true,"sensitive":false},{"name":"password","label":"Password","type":"password","required":true,"sensitive":true}]}` + fixture := fmt.Sprintf(`{"id":"credential-1","key":"login","type":"credential","version":1,"spec":%s,"state":{"status":"pending_collection","fields":{"username":{"has_value":false},"password":{"has_value":false}}},"available_operations":[],"available_expansions":[]}`, spec) + sent := "" + client := vaultTestClient(t, func(w http.ResponseWriter, r *http.Request) { + var body struct { + Spec struct { + Fields json.RawMessage `json:"fields"` + } `json:"spec"` + } + require.NoError(t, json.NewDecoder(r.Body).Decode(&body)) + sent = string(body.Spec.Fields) + w.Header().Set("Content-Type", "application/json") + io.WriteString(w, fixture) + }) + out, _, err := executeVaultCommand(t, client, "vaults", "credentials", "create", "user-123", "login", "--spec-file", credentialSpecFile(t, spec), "-o", "json") + require.NoError(t, err) + assert.Contains(t, sent, `"label":"Username or email"`) + assert.Contains(t, sent, `"label":"Password"`) + assert.Contains(t, out, `"label": "Username or email"`) + assert.Contains(t, out, `"label": "Password"`) +} + +// A label is metadata only; it must never carry a value into the output. +func TestVaultCredentialLabelDoesNotExposeValues(t *testing.T) { + fixture := strings.Replace(publicCredentialFixture, + `{"name":"password","type":"password"}`, + `{"name":"password","label":"Password","type":"password"}`, 1) + require.NotEqual(t, publicCredentialFixture, fixture) + out, err := filterVaultJSON(json.RawMessage(fixture), vaultItemFields) + require.NoError(t, err) + assert.Contains(t, string(out), `"label":"Password"`) + assert.NotContains(t, string(out), "private-password") +} diff --git a/cmd/vaults_sdk_contract_test.go b/cmd/vaults_sdk_contract_test.go index 8fa3a16c..802591fb 100644 --- a/cmd/vaults_sdk_contract_test.go +++ b/cmd/vaults_sdk_contract_test.go @@ -124,3 +124,51 @@ func TestVaultPreparationEventsAreProjected(t *testing.T) { assert.Contains(t, out, `"preparation_id": "prep-1"`) assert.NotContains(t, out, "never-print") } + +func TestCredentialFieldOrderIsPreserved(t *testing.T) { + t.Setenv("KERNEL_PROJECT", "") + spec := `{"description":"Example","fields":[{"name":"email","type":"email","required":true,"sensitive":false},{"name":"password","type":"password","required":true,"sensitive":true},{"name":"otp","type":"totp","required":false,"sensitive":true}]}` + client := vaultTestClient(t, func(w http.ResponseWriter, r *http.Request) { + var body struct { + Spec struct { + Fields json.RawMessage `json:"fields"` + } `json:"spec"` + } + require.NoError(t, json.NewDecoder(r.Body).Decode(&body)) + // The website's top-to-bottom order must reach the API unchanged. + assert.Equal(t, `[{"name":"email","type":"email","required":true,"sensitive":false},{"name":"password","type":"password","required":true,"sensitive":true},{"name":"otp","type":"totp","required":false,"sensitive":true}]`, string(body.Spec.Fields)) + w.Header().Set("Content-Type", "application/json") + fmt.Fprintf(w, `{"id":"credential-1","key":"login","type":"credential","version":1,"spec":%s,"state":{"status":"pending_collection","fields":{"email":{"has_value":false},"password":{"has_value":false},"otp":{"has_value":false}}},"available_operations":[],"available_expansions":[]}`, spec) + }) + out, _, err := executeVaultCommand(t, client, "vaults", "credentials", "create", "user-123", "login", "--spec-file", credentialSpecFile(t, spec), "-o", "json") + require.NoError(t, err) + assert.Less(t, strings.Index(out, `"email"`), strings.Index(out, `"password"`)) + assert.Less(t, strings.Index(out, `"password"`), strings.Index(out, `"otp"`)) + for _, name := range []string{"email", "password", "otp"} { + assert.Contains(t, out, fmt.Sprintf(`"name": %q`, name)) + } +} + +func TestCredentialKeyedFieldsAreRejectedWithGuidance(t *testing.T) { + t.Setenv("KERNEL_PROJECT", "") + client := vaultTestClient(t, func(w http.ResponseWriter, r *http.Request) { + t.Error("a keyed create spec must not reach the API") + }) + _, _, err := executeVaultCommand(t, client, "vaults", "credentials", "create", "user-123", "login", + "--spec-file", credentialSpecFile(t, `{"fields":{"password":{"type":"password","value":"secret-echo"}}}`)) + require.Error(t, err) + assert.Contains(t, err.Error(), "ordered array") + assert.NotContains(t, err.Error(), "secret-echo") +} + +func TestCredentialFieldsRequireNames(t *testing.T) { + t.Setenv("KERNEL_PROJECT", "") + client := vaultTestClient(t, func(w http.ResponseWriter, r *http.Request) { + t.Error("an unnamed field must not reach the API") + }) + _, _, err := executeVaultCommand(t, client, "vaults", "credentials", "create", "user-123", "login", + "--spec-file", credentialSpecFile(t, `{"fields":[{"type":"password","value":"secret-echo"}]}`)) + require.Error(t, err) + assert.Contains(t, err.Error(), "name") + assert.NotContains(t, err.Error(), "secret-echo") +} diff --git a/cmd/vaults_test.go b/cmd/vaults_test.go index 14942156..5ec933b3 100644 --- a/cmd/vaults_test.go +++ b/cmd/vaults_test.go @@ -303,6 +303,32 @@ func TestVaultCardRequestMapping(t *testing.T) { } } +func TestVaultCardAgentcardCardIDIsOpaque(t *testing.T) { + t.Setenv("KERNEL_PROJECT", "project-test") + // AgentCard card IDs are opaque: the CLI must forward whatever the caller + // supplies without assuming a prefix or format. + for _, cardID := range []string{"vc_chosen", "chosen", "card-123", "AGC/9f2e::7"} { + t.Run(cardID, func(t *testing.T) { + client := vaultTestClient(t, func(w http.ResponseWriter, r *http.Request) { + var body map[string]json.RawMessage + require.NoError(t, json.NewDecoder(r.Body).Decode(&body)) + var spec struct { + CardID string `json:"card_id"` + } + require.NoError(t, json.Unmarshal(body["spec"], &spec)) + assert.Equal(t, cardID, spec.CardID) + w.Header().Set("Content-Type", "application/json") + _, _ = io.WriteString(w, requestedCardFixture) + }) + spec := fmt.Sprintf(`{"wallet":"wallet-1","amount":1234,"currency":"usd","merchant":"Example Shop","card_id":%q}`, cardID) + _, _, err := executeVaultCommand(t, client, + "vaults", "cards", "create", "checkout", "order-1", "-o", "json", + "--provider", "agentcard", "--spec", spec) + require.NoError(t, err) + }) + } +} + func TestVaultInvokeRequiresAdvertisedOperation(t *testing.T) { t.Setenv("KERNEL_PROJECT", "project-test") for _, state := range []string{"requested", "pending_authorization", "ready", "consumed", "expired", "declined"} { diff --git a/go.mod b/go.mod index dcae6b62..48c594a9 100644 --- a/go.mod +++ b/go.mod @@ -9,7 +9,7 @@ require ( github.com/charmbracelet/lipgloss/v2 v2.0.0-beta.1 github.com/golang-jwt/jwt/v5 v5.2.2 github.com/joho/godotenv v1.5.1 - github.com/kernel/kernel-go-sdk v0.110.0 + github.com/kernel/kernel-go-sdk v0.111.1-0.20260922230520-0584ea1d2238 github.com/klauspost/compress v1.18.5 github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c github.com/pterm/pterm v0.12.80 diff --git a/go.sum b/go.sum index 1f47cec9..25c30f90 100644 --- a/go.sum +++ b/go.sum @@ -64,8 +64,8 @@ github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0= github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4= -github.com/kernel/kernel-go-sdk v0.110.0 h1:2KkE0hAlJav5xg2818Eg+mIK2p1F2nDZ0rZdA2EO1QQ= -github.com/kernel/kernel-go-sdk v0.110.0/go.mod h1:EeZzSuHZVeHKxKCPUzxou2bovNGhXaz0RXrSqKNf1AQ= +github.com/kernel/kernel-go-sdk v0.111.1-0.20260922230520-0584ea1d2238 h1:YIXkHOZ6bpmZ8W1LtXHbAxpywu6bMZLROq8lWd9//yw= +github.com/kernel/kernel-go-sdk v0.111.1-0.20260922230520-0584ea1d2238/go.mod h1:EeZzSuHZVeHKxKCPUzxou2bovNGhXaz0RXrSqKNf1AQ= github.com/klauspost/compress v1.18.5 h1:/h1gH5Ce+VWNLSWqPzOVn6XBO+vJbCNGvjoaGBFW2IE= github.com/klauspost/compress v1.18.5/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ= github.com/klauspost/cpuid/v2 v2.0.9/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=