Kits issue after upgrading to 0.31.1: unmarshal errors

[HofmeisterAn]

After upgrading from version 0.30.0 to 0.31.1, the configuration we had set up to run with GHE no longer works on Windows and fails with the following error:

PS C:\Users\<username>\Desktop\docker-sandbox-kit> sbx run --kit . copilot-dotnet
Starting sandboxd daemon...
Daemon started (PID: 18156, socket: \\.\pipe\docker_kaname_sandboxd)
Logs: C:\Users\<username>\AppData\Local\DockerSandboxes\sandboxes\state\sandboxd\daemon.log
ERROR: resolve kits: kit ".": artifact: invalid spec.yaml: yaml: unmarshal errors:
  line 13: field persistence not found in type spec.agentBlock
  line 213: field build not found in type spec.CommandsPolicy
  line 216: field test not found in type spec.CommandsPolicy

This is the configuration that worked previously with 0.30.0:

schemaVersion: "1"
kind: agent
name: copilot-dotnet
displayName: GitHub Copilot + .NET 10
description: >-
  Standalone Copilot agent with .NET SDK 10. GH_TOKEN is read from the
  host environment and injected by the Docker Sandbox proxy. The token
  never enters the VM. Pair with the balanced host policy:
  (sbx policy set-default balanced).
agent:
  image: docker/sandbox-templates:copilot-docker
  aiFilename: AGENTS.md
  persistence: persistent
  entrypoint:
    run:
      - copilot
commands:
  initFiles:
    - path: /usr/local/share/ca-certificates/ca-bundle.crt
      mode: 0644
      content: |
        <PLACEHOLDER>
      onlyIfMissing: true
  install:
    - command: update-ca-certificates
      description: Update CA Certificates
    - command: apt-get update && apt-get install -y --no-install-recommends dotnet-sdk-10.0
      description: Install .NET SDK 10
    - command: dotnet --version
      description: Verify .NET SDK install
  build:
    - command: dotnet build
      description: Build .NET project
  test:
    - command: dotnet test
      description: Run .NET tests
network:
  serviceDomains:
    foo.ghe.com: github
    api.foo.ghe.com: github
    copilot-api.foo.ghe.com: github
  serviceAuth:
    github:
      headerName: Authorization
      valueFormat: Bearer %s
  allowedDomains:
    - "github.com"
    - "foo.ghe.com"
    - "api.foo.ghe.com"
    - "copilot-api.foo.ghe.com"
credentials:
  sources:
    github:
      env:
        - GH_TOKEN
environment:
  variables:
    GH_HOST: foo.ghe.com

[kiview]

Sorry for breaking you @HofmeisterAn 😿
We are currently making changes to the kit spec to ensure a stable long-term format (not yet finalized), but we should do a better job and migrating and informing existing users.

[HofmeisterAn]

No worries, I can downgrade the version for now. I just wanted to share the regression 👍. If I can test smth let me know.

[mdelapenya]

Hey @HofmeisterAn 👋 , thanks a ton for raising this. First, sorry it took down your setup; let me walk you through what's going on so you can get back to running on the latest.

TL;DR

The fix is small: delete persistence: persistent, and drop the build: / test: blocks under commands:. All three were actually already no-ops on 0.30.0, although you just couldn't tell because the parser was silently swallowing them.

What changed between 0.30.0 and 0.31.1

In 0.31.0 we bumped sbx-kits-contrib to a version that decodes spec.yaml in strict mode (yaml.Decoder.KnownFields(true)). Before 0.31.0 the parser was lenient: unknown fields got silently dropped. Flipping strict mode on is what surfaced these errors, but none of the three fields were doing anything on 0.30.0 either.

The three fields, one at a time

1. persistence: persistent (line 13)

agent:
  image: docker/sandbox-templates:copilot-docker
  aiFilename: AGENTS.md
  # persistence: persistent      ← delete (was a no-op on 0.30.0 already)
  entrypoint:
    run:
      - copilot
commands:
  initFiles:
    - path: /usr/local/share/ca-certificates/ca-bundle.crt
      mode: 0644
      content: |
        <PLACEHOLDER>
      onlyIfMissing: true
  install:
    - command: update-ca-certificates
      description: Update CA Certificates
    - command: apt-get update && apt-get install -y --no-install-recommends dotnet-sdk-10.0
      description: Install .NET SDK 10
    - command: dotnet --version
      description: Verify .NET SDK install
    # If you want `dotnet build` / `dotnet test` to run at comands.install or commands.startup time,
    # add them here. They were never running from commands.build /
    # commands.test — those keys were silently dropped by the old parser.
# network / credentials / environment blocks unchanged

2. commands.build (line 213) + commands.test (line 216)

These were never valid fields in the kit spec. The commands: block has always only supported install, startup, and initFiles: I checked every published version of sbx-kits-contrib (10 of them, from the first pre-release through what 0.31.1 ships), and build / test never existed at any point.

On 0.30.0 the non-strict parser dropped them on the floor, which means your dotnet build / dotnet test were never actually being executed during sandbox creation. The silver lining is: nothing of value is being lost by removing them.

If you want a quick sanity check, you can confirm on 0.30.0 by sticking dotnet build && exit 99 under commands.install (which definitely runs) and watching it fail; then move the same command back to commands.build: and watch the sandbox start cleanly without ever touching it.

If you want those commands to run at install or startup time going forward, fold them into commands.install or commands.startup, respectively.

I'd say that adding a memory file for your kit would help the agent in actually knowing what command to run for building or running the tests. But OTOH, I'm also pretty sure agents are already aware of the dotnet lifecycle. So they probably know with no memory block.

[HofmeisterAn]

Thanks, @mdelapenya.

build / test never existed at any point.

Hmm, interesting. I'm not sure where I got that info from. I believe the docs gave me the impression that I could add custom commands there as well, but that was probably a misunderstanding. I can't find anything related to that now, so thanks for the clarification.

delete persistence: persistent, and drop the build: / test: blocks

Removing those parts works, thanks. Unfortunately, I've now run into the following issue:

ERROR: failed to create sandbox: create sandbox: create sandbox: run sandbox: start container: started hook: kit "copilot-dotnet" (C:\Users<username>\Desktop\docker-sandbox-kit): commands.initFiles[0] (/usr/local/share/> ca-certificates/ca-bundle.crt): exited 2 after 15ms
── captured output ──
sh: 1: cannot create /usr/local/share/ca-certificates/ca-bundle.crt: Permission denied

It looks like the user that runs initFiles has changed. A user field doesn't seem to exist for initFiles like it does for the others.

Edit:

I also think it's necessary to move the certs installation to the install field (from the docs):

install:

Install commands run once at creation

initFIles:

Files written at sandbox start, with runtime substitution.

Otherwise, update-ca-certificates runs too early.

[mdelapenya]

@HofmeisterAn I'm re-adding the removed fields to the validation warnings (see docker/sbx-kits-contrib#73), and I'll eventually update the release notes to mention they were changed, for users to be notified with the release notes.

Thanks for your report!