From 0b998bcd7d75452e828b14064c737dee05fb0e4e Mon Sep 17 00:00:00 2001 From: Jeremy Cohn Date: Tue, 18 Aug 2026 13:54:30 -0700 Subject: [PATCH 1/2] docs: explain context infrastructure Signed-off-by: Jeremy Cohn --- README.md | 30 +++++++++++ cmd/contexts.go | 20 ++++++- cmd/contexts_test.go | 44 ++++++++++++++++ docs/README.md | 7 ++- docs/context-infrastructure.md | 95 ++++++++++++++++++++++++++++++++++ 5 files changed, 193 insertions(+), 3 deletions(-) create mode 100644 docs/context-infrastructure.md diff --git a/README.md b/README.md index 2f61a94..88a39dc 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,36 @@ rossoctl login rossoctl agents list ``` +## Agent context infrastructure + +`rossoctl context` manages durable files made available to agents. A context +resource can represent a mutable workspace, durable memory, reusable knowledge, +or produced artifacts. Today all four types use PVC-backed storage mounted into +StatefulSet or Sandbox agents. + +This meaning is separate from both: + +- the kubectl-style connection contexts managed by `rossoctl config`; and +- an LLM's finite context window. + +```sh +# Create and inspect a shared workspace. +rossoctl context create research --shared --size 10Gi \ + --storage-class ibm-scale-csi +rossoctl context list + +# Mount it when importing an agent. +rossoctl agents import --deployment-type sandbox \ + --context research:/workspace \ + from-image --name researcher --containerImage IMAGE +``` + +Context commands require a Rosso server containing the context resource API +introduced by [rossoctl/rossoctl#2392](https://github.com/rossoctl/rossoctl/pull/2392). +An older server returns an actionable compatibility error from `context list`. +See [Context infrastructure](docs/context-infrastructure.md) for the model, +lifecycle, storage behavior, and additional examples. + ## Running a command behind an AuthBridge pipeline Rossoctl can be used to test how an agent runs under an AuthBridge configuration on your laptop. It provides an in-process implementation of AuthBridge. diff --git a/cmd/contexts.go b/cmd/contexts.go index 42e2e72..e2c7642 100644 --- a/cmd/contexts.go +++ b/cmd/contexts.go @@ -2,7 +2,9 @@ package cmd import ( "encoding/json" + "errors" "fmt" + "net/http" "text/tabwriter" "github.com/spf13/cobra" @@ -12,6 +14,14 @@ import ( var contextsNamespace string +func contextListError(err error) error { + var statusErr *apiclient.StatusError + if errors.As(err, &statusErr) && statusErr.StatusCode == http.StatusNotFound { + return fmt.Errorf("this Rosso server does not support context infrastructure; context commands require the context resource API introduced by rossoctl/rossoctl#2392: %w", err) + } + return err +} + func contextNamespace() (string, error) { if contextsNamespace != "" { return contextsNamespace, nil @@ -128,7 +138,7 @@ func newContextsListCmd() *cobra.Command { } result, err := client.ListContexts(cmd.Context(), namespace) if err != nil { - return err + return contextListError(err) } if jsonOutput { encoded, err := json.MarshalIndent(result.Items, "", " ") @@ -194,8 +204,14 @@ func printContextResource(cmd *cobra.Command, value *apiclient.ContextResource, } func init() { - contextsCmd := newGroup("contexts", "Manage named agent context resources") + contextsCmd := newGroup("contexts", "Manage durable context infrastructure for agents") contextsCmd.Aliases = []string{"context"} + contextsCmd.Long = `Manage durable context infrastructure for agents. + +Context resources make files available to agents as workspaces, memory, +knowledge, or artifacts. They are distinct from rossoctl configuration +contexts and from an LLM's finite context window. The current backend is +PVC-backed storage mounted into StatefulSet or Sandbox agents.` contextsCmd.PersistentFlags().StringVar(&contextsNamespace, "namespace", "", "namespace (overrides current context)") contextsCmd.AddCommand(newContextsCreateCmd(), newContextsListCmd(), newContextsGetCmd(), newContextsDeleteCmd()) rootCmd.AddCommand(contextsCmd) diff --git a/cmd/contexts_test.go b/cmd/contexts_test.go index a6e693b..8ed8fb2 100644 --- a/cmd/contexts_test.go +++ b/cmd/contexts_test.go @@ -87,6 +87,33 @@ func TestContextsList(t *testing.T) { } } +func TestContextsListExplainsUnsupportedServer(t *testing.T) { + isolateHome(t) + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json") + switch r.URL.Path { + case "/api/v1/namespaces": + _, _ = w.Write([]byte(`{"namespaces":["team1"]}`)) + case "/api/v1/contexts/team1": + http.Error(w, `{"detail":"Not Found"}`, http.StatusNotFound) + default: + t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path) + } + })) + defer srv.Close() + setupImportContext(t, srv, "team1") + + _, err := execute(t, "contexts", "list") + if err == nil { + t.Fatal("expected an unsupported-server error") + } + for _, expected := range []string{"does not support context infrastructure", "rossoctl/rossoctl#2392"} { + if !strings.Contains(err.Error(), expected) { + t.Errorf("error missing %q: %v", expected, err) + } + } +} + func TestContextAlias(t *testing.T) { command, _, err := rootCmd.Find([]string{"context", "list"}) if err != nil { @@ -133,3 +160,20 @@ func TestContextCreateHelpIncludesExamples(t *testing.T) { } } } + +func TestContextGroupHelpDefinesContextInfrastructure(t *testing.T) { + out, err := execute(t, "context", "--help") + if err != nil { + t.Fatal(err) + } + for _, expected := range []string{ + "durable context infrastructure for agents", + "distinct from rossoctl configuration", + "LLM's finite context window", + "PVC-backed storage", + } { + if !strings.Contains(out, expected) { + t.Errorf("context help missing %q:\n%s", expected, out) + } + } +} diff --git a/docs/README.md b/docs/README.md index 4415281..c7b0877 100644 --- a/docs/README.md +++ b/docs/README.md @@ -13,6 +13,12 @@ ships prebuilt binaries built by `.github/workflows/release.yml`; the asset names are `rossoctl---.tar.gz` (arm64 is labeled `arm64` on both Linux and Darwin). +## Feature documentation + +- [Context infrastructure](context-infrastructure.md) explains named agent + context resources, their relationship to storage, and how they differ from + rossoctl configuration contexts and LLM context windows. + ## Layout This project follows the standard Go CLI layout: @@ -136,4 +142,3 @@ assert on the command strings they would run rather than invoking a real runtime to `main`, plus a `go mod tidy` check. Shuffled order is included because the suite mutates process state (`HOME`, cobra flag values), so an order-dependent test is a real risk — see the pflag hazard documented in `cmd/root_test.go`. - diff --git a/docs/context-infrastructure.md b/docs/context-infrastructure.md new file mode 100644 index 0000000..6f58079 --- /dev/null +++ b/docs/context-infrastructure.md @@ -0,0 +1,95 @@ +# Context infrastructure + +Agentic applications need more than an LLM context window. They work with +checked-out repositories, intermediate files, durable observations, reference +material, and generated results. Rosso calls the infrastructure that provisions +and attaches those resources **context infrastructure**. + +The `context` name is intentional. It describes information and working state +made available to an agent, rather than only the storage mechanism used to hold +it. It is distinct from: + +- a **rossoctl configuration context**, which selects an API server, namespace, + and credential and is managed with `rossoctl config`; and +- an **LLM context window**, which is the bounded prompt and conversation sent + to a model for one inference. + +## Resource model + +A named context resource records semantic intent separately from storage +configuration: + +| Type | Intended role | Current implementation | +| --- | --- | --- | +| `workspace` | Mutable files used while an agent works | PVC | +| `memory` | Durable observations and experiences | PVC | +| `knowledge` | Synthesized, reusable understanding | PVC | +| `artifacts` | Reports, media, and other produced outputs | PVC | + +The type is metadata today. It does not yet change provisioning, lifecycle, or +access policy. Keeping it separate from the backend allows future implementations +such as object storage or cached object-backed filesystems without changing how +users describe the role of the resource. + +```text +Context Service Rosso Agent +--------------- ----- ----- +provisions named storage --> resolves the attachment --> mounts the PVC +returns a PVC attachment while importing an agent at the chosen path +``` + +Contexts have an independent lifecycle. Deleting an agent does not delete its +context, allowing another agent to mount the same resource. Delete it explicitly +when it is no longer needed. + +## Examples + +Create a private ReadWriteOnce workspace: + +```sh +rossoctl context create research --size 5Gi +``` + +Create a shared ReadWriteMany workspace: + +```sh +rossoctl context create shared-research \ + --shared --size 10Gi --storage-class ibm-scale-csi +``` + +Create resources with other semantic roles: + +```sh +rossoctl context create research-memory --type memory --size 5Gi +rossoctl context create research-library --type knowledge --shared --size 20Gi +rossoctl context create research-results --type artifacts --shared --size 20Gi +``` + +Mount a context into a StatefulSet or Sandbox agent: + +```sh +rossoctl agents import --deployment-type statefulset \ + --context research:/workspace \ + from-image --name researcher --containerImage IMAGE + +rossoctl agents import --deployment-type sandbox \ + --context shared-research:/workspace \ + from-image --name reviewer --containerImage IMAGE +``` + +Inspect and remove resources: + +```sh +rossoctl context list +rossoctl context get research +rossoctl context delete research +``` + +## Server compatibility + +The CLI commands require the context resource API introduced by +[rossoctl/rossoctl#2392](https://github.com/rossoctl/rossoctl/pull/2392). Until it +appears in a numbered Rosso release, use a server built from a later `main` +commit. `rossoctl context list` identifies the common older-server 404 and +explains that the server must be upgraded instead of returning only the raw +HTTP error. From 4dec4510363011cee57000dfbc14cd4534454eb9 Mon Sep 17 00:00:00 2001 From: Jeremy Cohn Date: Tue, 18 Aug 2026 14:25:26 -0700 Subject: [PATCH 2/2] docs: point context help to Rosso concepts Signed-off-by: Jeremy Cohn --- README.md | 26 ++++++---- cmd/contexts.go | 5 +- cmd/contexts_test.go | 1 + docs/README.md | 6 --- docs/context-infrastructure.md | 95 ---------------------------------- 5 files changed, 20 insertions(+), 113 deletions(-) delete mode 100644 docs/context-infrastructure.md diff --git a/README.md b/README.md index 88a39dc..9e7e81a 100644 --- a/README.md +++ b/README.md @@ -31,15 +31,12 @@ rossoctl agents list ## Agent context infrastructure -`rossoctl context` manages durable files made available to agents. A context -resource can represent a mutable workspace, durable memory, reusable knowledge, -or produced artifacts. Today all four types use PVC-backed storage mounted into -StatefulSet or Sandbox agents. - -This meaning is separate from both: - -- the kubectl-style connection contexts managed by `rossoctl config`; and -- an LLM's finite context window. +`rossoctl context` creates, lists, and attaches the context resources provided +by Rosso's optional Context Service integration. See Rosso's canonical +[Context Service documentation](https://github.com/rossoctl/rossoctl/blob/main/docs/concepts/context-service.md) +for the resource model, storage behavior, and lifecycle. The underlying service +is maintained in the +[context-service repository](https://github.com/rossoctl/context-service). ```sh # Create and inspect a shared workspace. @@ -56,8 +53,15 @@ rossoctl agents import --deployment-type sandbox \ Context commands require a Rosso server containing the context resource API introduced by [rossoctl/rossoctl#2392](https://github.com/rossoctl/rossoctl/pull/2392). An older server returns an actionable compatibility error from `context list`. -See [Context infrastructure](docs/context-infrastructure.md) for the model, -lifecycle, storage behavior, and additional examples. + +To try the commands from the latest source: + +```sh +git clone https://github.com/rossoctl/rossoctl-cli.git +cd rossoctl-cli +make build +./bin/rossoctl context --help +``` ## Running a command behind an AuthBridge pipeline diff --git a/cmd/contexts.go b/cmd/contexts.go index e2c7642..a6d0a94 100644 --- a/cmd/contexts.go +++ b/cmd/contexts.go @@ -211,7 +211,10 @@ func init() { Context resources make files available to agents as workspaces, memory, knowledge, or artifacts. They are distinct from rossoctl configuration contexts and from an LLM's finite context window. The current backend is -PVC-backed storage mounted into StatefulSet or Sandbox agents.` +PVC-backed storage mounted into StatefulSet or Sandbox agents. + +Learn more: +https://github.com/rossoctl/rossoctl/blob/main/docs/concepts/context-service.md` contextsCmd.PersistentFlags().StringVar(&contextsNamespace, "namespace", "", "namespace (overrides current context)") contextsCmd.AddCommand(newContextsCreateCmd(), newContextsListCmd(), newContextsGetCmd(), newContextsDeleteCmd()) rootCmd.AddCommand(contextsCmd) diff --git a/cmd/contexts_test.go b/cmd/contexts_test.go index 8ed8fb2..9863819 100644 --- a/cmd/contexts_test.go +++ b/cmd/contexts_test.go @@ -171,6 +171,7 @@ func TestContextGroupHelpDefinesContextInfrastructure(t *testing.T) { "distinct from rossoctl configuration", "LLM's finite context window", "PVC-backed storage", + "docs/concepts/context-service.md", } { if !strings.Contains(out, expected) { t.Errorf("context help missing %q:\n%s", expected, out) diff --git a/docs/README.md b/docs/README.md index c7b0877..32792b1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -13,12 +13,6 @@ ships prebuilt binaries built by `.github/workflows/release.yml`; the asset names are `rossoctl---.tar.gz` (arm64 is labeled `arm64` on both Linux and Darwin). -## Feature documentation - -- [Context infrastructure](context-infrastructure.md) explains named agent - context resources, their relationship to storage, and how they differ from - rossoctl configuration contexts and LLM context windows. - ## Layout This project follows the standard Go CLI layout: diff --git a/docs/context-infrastructure.md b/docs/context-infrastructure.md deleted file mode 100644 index 6f58079..0000000 --- a/docs/context-infrastructure.md +++ /dev/null @@ -1,95 +0,0 @@ -# Context infrastructure - -Agentic applications need more than an LLM context window. They work with -checked-out repositories, intermediate files, durable observations, reference -material, and generated results. Rosso calls the infrastructure that provisions -and attaches those resources **context infrastructure**. - -The `context` name is intentional. It describes information and working state -made available to an agent, rather than only the storage mechanism used to hold -it. It is distinct from: - -- a **rossoctl configuration context**, which selects an API server, namespace, - and credential and is managed with `rossoctl config`; and -- an **LLM context window**, which is the bounded prompt and conversation sent - to a model for one inference. - -## Resource model - -A named context resource records semantic intent separately from storage -configuration: - -| Type | Intended role | Current implementation | -| --- | --- | --- | -| `workspace` | Mutable files used while an agent works | PVC | -| `memory` | Durable observations and experiences | PVC | -| `knowledge` | Synthesized, reusable understanding | PVC | -| `artifacts` | Reports, media, and other produced outputs | PVC | - -The type is metadata today. It does not yet change provisioning, lifecycle, or -access policy. Keeping it separate from the backend allows future implementations -such as object storage or cached object-backed filesystems without changing how -users describe the role of the resource. - -```text -Context Service Rosso Agent ---------------- ----- ----- -provisions named storage --> resolves the attachment --> mounts the PVC -returns a PVC attachment while importing an agent at the chosen path -``` - -Contexts have an independent lifecycle. Deleting an agent does not delete its -context, allowing another agent to mount the same resource. Delete it explicitly -when it is no longer needed. - -## Examples - -Create a private ReadWriteOnce workspace: - -```sh -rossoctl context create research --size 5Gi -``` - -Create a shared ReadWriteMany workspace: - -```sh -rossoctl context create shared-research \ - --shared --size 10Gi --storage-class ibm-scale-csi -``` - -Create resources with other semantic roles: - -```sh -rossoctl context create research-memory --type memory --size 5Gi -rossoctl context create research-library --type knowledge --shared --size 20Gi -rossoctl context create research-results --type artifacts --shared --size 20Gi -``` - -Mount a context into a StatefulSet or Sandbox agent: - -```sh -rossoctl agents import --deployment-type statefulset \ - --context research:/workspace \ - from-image --name researcher --containerImage IMAGE - -rossoctl agents import --deployment-type sandbox \ - --context shared-research:/workspace \ - from-image --name reviewer --containerImage IMAGE -``` - -Inspect and remove resources: - -```sh -rossoctl context list -rossoctl context get research -rossoctl context delete research -``` - -## Server compatibility - -The CLI commands require the context resource API introduced by -[rossoctl/rossoctl#2392](https://github.com/rossoctl/rossoctl/pull/2392). Until it -appears in a numbered Rosso release, use a server built from a later `main` -commit. `rossoctl context list` identifies the common older-server 404 and -explains that the server must be upgraded instead of returning only the raw -HTTP error.