feat(kitrun): mount the operator's skills store for agent-skills@1

A Kit's agent-skills@1 path now gets the shared skills store
(skills_dir/.agents/skills) bind-mounted read-only, whatever mode the Kit
asks for; with no skills_dir the host withholds the mount. skills_dir is
read live on every launch. skill.StoreDir exposes the store path so the
launcher does not copy the package's directory constant.

Part of archie-core-egkf.6.
This commit is contained in:
sam committed 2026-09-28 02:12:29 +10:00
1 parent b867275791
commit 70f9b1b87c
7 files changed
+90 -35

No files matched your search

@@ -107,7 +107,7 @@ Do not expose these helper flags as daemon settings.
| Keys | Default, validation, and consumer | Status |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `work_dir`, `state_dir` | Derive from `$XDG_DATA_HOME/archie`, else `$HOME/.local/share/archie`; explicit `~` paths are home-expanded. `state_dir` holds the embedded NATS store and endpoint file, task logs and the readiness disk target. | production-wired |
| `skills_dir` | Empty falls back to `work_dir` for startup workflow registry. | partially-wired |
| `skills_dir` | Empty falls back to `work_dir` for startup workflow registry. Also the skills store `kitrun.Launcher` mounts read-only at a Kit's `agent-skills@1` path, read live per launch; empty withholds the mount. | partially-wired |
| `plugin_dir` | Empty disables daemon plugin loading; configured directory loaded in `internal/app/archied`. | production-wired |
| `poll_interval` | Default `60s`; root poll loop uses it, identities may override only interval. | production-wired |
| `label` | No default or validation; used for `dispatch.trigger = "label"` or `"either"`. | production-wired |
+1 -1
View File
@@ -328,7 +328,7 @@
"url": "/dev/prds/external-agent-harness/",
"title": "External agent harnesses",
"section": "PRDs",
"body": "# External agent harnesses\n\n**Status:** Approved\n**Authority:** `docs/architecture/agent-system.md` (agent execution as a data\nboundary); settles the harness non-goal deferred by\n`docs/prds/service-decomposition.md`.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (a harness\nrun is one `agent` StepExecution), `docs/prds/binding-secret-encryption.md`\n(the at-rest envelope reused for harness credentials).\n\n## Decision\n\nA workflow stage can run on an external coding-agent CLI instead of the\nbuilt-in agent loop: Claude Code, Codex, Pi, OMP, GitHub Copilot CLI, or any\nother CLI packaged as a Docker Sandbox Kit v3. Each authenticates with an API\nkey or the operator's subscription login, and can carry the operator's own\nskills, plugins, subagents and instructions.\n\nTwo boundaries hold regardless of what the harness does:\n\n- **The real credential never enters the container.** The container sees\n sentinel values; archie's egress proxy substitutes the real credential on\n outbound requests and performs OAuth refresh on the host.\n- **Archie's workflow guarantees are enforced outside the harness.** Git,\n protected paths, read-only stages, gates and budgets are checked by archie\n around the process and against the worktree afterwards.\n\n## Kits\n\nA harness is packaged as a Kit v3 image: an OCI image whose\n`vnd.docker.sandbox.kit.descriptor` manifest annotation declares what the\nharness needs. Archie reads descriptors with the published\n`github.com/docker/sandbox-kit-spec/v3/spec` package and does not maintain\nits own descriptor format. Published Kits run unmodified.\n\nArchie is a partial Kit runtime. It implements these capability types:\n\n| Type | Archie behaviour |\n| ------------------- | ----------------------------------------------------------------------------------------- |\n| `credential@1` | Proxy-managed only, described below. |\n| `network-policy@1` | Enforced by the egress proxy. |\n| `volume@1` | A Docker volume keyed by WorkflowExecution, deleted with it. |\n| `lifecycle@1` | Install and startup hooks run on container create. |\n| `agent-sessions@1` | The headless `prompt` and `resume` invocations for the stage. |\n| `agent-skills@1` | The operator's skills store, mounted read-only whatever the Kit asks. |\n| `agent-context@1` | Archie's stage instructions, delivered where the Kit declares. |\n| `resources@1` | Container CPU and memory limits. |\n\nEvery other type fails closed: a required entry refuses the launch, an\noptional one is skipped and recorded on the step. `credential@1` with\n`passthrough: true` and any credential for a forge service are refused.\n\nThe operator's own setup (plugins, subagents, instructions, settings) is a\nmixin Kit, published with the harness Kit as a Kit set: the set merges their\nlayers into one image. It is versioned image content, rewritten on every\ncreate, never state a run can modify.\n\n## Contract\n\nA harness run is a second implementation of `agentexec.Runner`. It takes the\nsame `Request` and returns the same `Result`, so workflows, the daemon and\nthe State Store do not know which runner ran a stage.\n\n`agent-sessions@1` supplies the invocation. Archie supplies, per CLI, an\noutput adapter that translates the CLI's JSON output stream into\n`ToolCallReporter` calls, `Usage` and a session ID. A CLI with no adapter can\nrun stages with no capture tools, reporting no usage; its token budget falls\nback to wall clock.\n\nWorkflow definition validation rejects, at load time, a stage whose needs the\nselected harness cannot meet: capture tools without an adapter, or a gate\nretry without a `resume` verb.\n\n## Selection\n\nA harness is an agent profile. `docs/prds/event-automation.md` defines a\nprofile as the execution environment a workflow selects; a harness profile\nnames one Kit pinned by digest, a workload Kit or a published Kit set, in\nplace of a container image. Archie runs that Kit's image and composes no Kits\nitself; a bare mixin is refused. Everything else about profiles\nholds: a workflow names its profile, a stage may name a different one, and a\nprofile holds no secrets.\n\n`archie-agent` builds the stage's runner from the stage's profile: the\nai-sdk agent loop for an image profile, the harness runner for a Kit\nprofile. Image profiles, and every workflow already written against them,\nare unchanged. A Kit profile named by no workflow is a validation error.\n\nA stage naming a different profile than its workflow's is a separate run,\nnot a mid-container runnLine truncated
"body": "# External agent harnesses\n\n**Status:** Approved\n**Authority:** `docs/architecture/agent-system.md` (agent execution as a data\nboundary); settles the harness non-goal deferred by\n`docs/prds/service-decomposition.md`.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (a harness\nrun is one `agent` StepExecution), `docs/prds/binding-secret-encryption.md`\n(the at-rest envelope reused for harness credentials).\n\n## Decision\n\nA workflow stage can run on an external coding-agent CLI instead of the\nbuilt-in agent loop: Claude Code, Codex, Pi, OMP, GitHub Copilot CLI, or any\nother CLI packaged as a Docker Sandbox Kit v3. Each authenticates with an API\nkey or the operator's subscription login, and can carry the operator's own\nskills, plugins, subagents and instructions.\n\nTwo boundaries hold regardless of what the harness does:\n\n- **The real credential never enters the container.** The container sees\n sentinel values; archie's egress proxy substitutes the real credential on\n outbound requests and performs OAuth refresh on the host.\n- **Archie's workflow guarantees are enforced outside the harness.** Git,\n protected paths, read-only stages, gates and budgets are checked by archie\n around the process and against the worktree afterwards.\n\n## Kits\n\nA harness is packaged as a Kit v3 image: an OCI image whose\n`vnd.docker.sandbox.kit.descriptor` manifest annotation declares what the\nharness needs. Archie reads descriptors with the published\n`github.com/docker/sandbox-kit-spec/v3/spec` package and does not maintain\nits own descriptor format. Published Kits run unmodified.\n\nArchie is a partial Kit runtime. It implements these capability types:\n\n| Type | Archie behaviour |\n| ------------------- | ----------------------------------------------------------------------------------------- |\n| `credential@1` | Proxy-managed only, described below. |\n| `network-policy@1` | Enforced by the egress proxy. |\n| `volume@1` | A Docker volume keyed by WorkflowExecution, deleted with it. |\n| `lifecycle@1` | Install and startup hooks run on container create. |\n| `agent-sessions@1` | The headless `prompt` and `resume` invocations for the stage. |\n| `agent-skills@1` | The operator's skills store (`skills_dir`), mounted read-only whatever the Kit asks. |\n| `agent-context@1` | The workload's profile file beside the workspace, indexing each Kit's guidance. |\n| `resources@1` | Container CPU and memory limits. |\n\nEvery other type fails closed: a required entry refuses the launch, an\noptional one is skipped and recorded on the step. `credential@1` with\n`passthrough: true` and any credential for a forge service are refused.\n\nThe operator's own setup (plugins, subagents, instructions, settings) is a\nmixin Kit, published with the harness Kit as a Kit set: the set merges their\nlayers into one image. It is versioned image content, rewritten on every\ncreate, never state a run can modify.\n\n## Contract\n\nA harness run is a second implementation of `agentexec.Runner`. It takes the\nsame `Request` and returns the same `Result`, so workflows, the daemon and\nthe State Store do not know which runner ran a stage.\n\n`agent-sessions@1` supplies the invocation. Archie supplies, per CLI, an\noutput adapter that translates the CLI's JSON output stream into\n`ToolCallReporter` calls, `Usage` and a session ID. A CLI with no adapter can\nrun stages with no capture tools, reporting no usage; its token budget falls\nback to wall clock.\n\nWorkflow definition validation rejects, at load time, a stage whose needs the\nselected harness cannot meet: capture tools without an adapter, or a gate\nretry without a `resume` verb.\n\n## Selection\n\nA harness is an agent profile. `docs/prds/event-automation.md` defines a\nprofile as the execution environment a workflow selects; a harness profile\nnames one Kit pinned by digest, a workload Kit or a published Kit set, in\nplace of a container image. Archie runs that Kit's image and composes no Kits\nitself; a bare mixin is refused. Everything else about profiles\nholds: a workflow names its profile, a stage may name a different one, and a\nprofile holds no secrets.\n\n`archie-agent` builds the stage's runner from the stage's profile: the\nai-sdk agent loop for an image profile, the harness runner for a Kit\nprofile. Image profiles, and every workflow already written against them,\nare unchanged. A Kit profile named by no workflow is a validation error.\n\nA stage naming a different profile than its workflow's is a separate run,\nnot a mid-container runnLine truncated
},
{
"url": "/dev/prds/identity-decision/",
+2 -2
View File
@@ -42,8 +42,8 @@ Archie is a partial Kit runtime. It implements these capability types:
| `volume@1` | A Docker volume keyed by WorkflowExecution, deleted with it. |
| `lifecycle@1` | Install and startup hooks run on container create. |
| `agent-sessions@1` | The headless `prompt` and `resume` invocations for the stage. |
| `agent-skills@1` | The operator's skills store, mounted read-only whatever the Kit asks. |
| `agent-context@1` | Archie's stage instructions, delivered where the Kit declares. |
| `agent-skills@1` | The operator's skills store (`skills_dir`), mounted read-only whatever the Kit asks. |
| `agent-context@1` | The workload's profile file beside the workspace, indexing each Kit's guidance. |
| `resources@1` | Container CPU and memory limits. |
Every other type fails closed: a required entry refuses the launch, an
+2 -1
View File
@@ -388,7 +388,8 @@ type Config struct {
// containing .agents/skills/*/SKILL.md files. When set, the
// daemon builds its workflow registry from the skill catalog
// (plugin-defined workflows override built-ins). When empty,
// only built-in workflows are available.
// only built-in workflows are available. Its skills are also the
// store a Kit's agent-skills@1 mounts, read-only, into the harness.
SkillsDir string `toml:"skills_dir" yaml:"skills_dir"`
// WorkflowRoutingFile is an optional path to a YAML file rebinding
// which registered workflow an intake Kind (bug/feature/bootstrap)
+65 -30
View File
@@ -19,6 +19,7 @@ import (
"github.com/samcharles93/archie-core/internal/container"
"github.com/samcharles93/archie-core/internal/infrastructure/egress"
"github.com/samcharles93/archie-core/internal/infrastructure/kit"
"github.com/samcharles93/archie-core/internal/skill"
)
// SecretResolver resolves a credential binding's secret value. *secret.Registry
@@ -119,26 +120,15 @@ func (l *Launcher) Launch(ctx context.Context, req Request) (*Run, error) {
if err := l.startEgress(ctx); err != nil {
return nil, err
}
plan, img, err := l.compose(ctx, req.Kit)
k, err := l.read(ctx, req.Kit, req.GateRetries)
if err != nil {
return nil, err
}
if err := kit.ValidateNeeds(plan, req.GateRetries); err != nil {
return nil, err
}
network, err := spec.NetworkPolicyOf(plan.Capabilities)
if err != nil {
return nil, err
}
creds, err := spec.CredentialsOf(plan.Capabilities)
if err != nil {
return nil, err
}
granted, bound := l.resolveCredentials(req, creds)
granted, bound := l.resolveCredentials(req, k.creds)
if l.Grants != nil {
l.Grants.Grant(req.Execution, granted)
}
session, err := l.Proxy.Register(egress.SessionOptions{Run: req.Execution, Org: req.Org, Network: network, Credentials: creds})
session, err := l.Proxy.Register(egress.SessionOptions{Run: req.Execution, Org: req.Org, Network: k.network, Credentials: k.creds})
if err != nil {
if l.Grants != nil {
l.Grants.RevokeGrant(req.Execution)
@@ -146,7 +136,7 @@ func (l *Launcher) Launch(ctx context.Context, req Request) (*Run, error) {
return nil, err
}
run := &Run{network: "archie-kit-" + req.Execution, token: session.Token(), execution: req.Execution}
launch, err := kit.Assemble(plan, img, kit.LaunchParams{Execution: req.Execution, ProxyToken: session.Token(), CAPath: caPath, Bound: bound})
launch, err := kit.Assemble(k.plan, k.img, kit.LaunchParams{Execution: req.Execution, ProxyToken: session.Token(), CAPath: caPath, Bound: bound})
if err != nil {
l.release(run)
return nil, err
@@ -163,11 +153,11 @@ func (l *Launcher) Launch(ctx context.Context, req Request) (*Run, error) {
Network: run.network,
Worker: []string{agentPath},
WorkerEnv: req.WorkerEnv,
Binds: []string{
Binds: append([]string{
l.AgentBinary + ":" + agentPath + ":ro",
l.CAFile + ":" + caPath + ":ro",
req.WorkDir + ":" + kit.WorkspaceDir,
},
}, skillsBinds(k.skills, l.skillsDir())...),
Launch: launch,
InstallDone: session.EnterRuntime,
})
@@ -235,25 +225,54 @@ func (l *Launcher) release(run *Run) {
l.Proxy.Revoke(run.token)
}
// compose reads the profile's Kit and the config of the image it runs.
func (l *Launcher) compose(ctx context.Context, ref string) (*kit.Plan, kit.ImageConfig, error) {
reqs := []fetch.Request{{Reference: ref}}
merged, err := l.Fetch.Assemble(ctx, reqs, kit.MergeOptions)
// kitNeeds is what a profile's Kit asks of its run, read from its admitted
// plan.
type kitNeeds struct {
plan *kit.Plan
img kit.ImageConfig
network *spec.PhasedNetwork
creds []spec.CredentialCapability
skills []spec.AgentSkillsCapability
}
// read fetches and admits the profile's Kit, checks it can meet the
// workflow's gate retries, and decodes what it asks of the run.
func (l *Launcher) read(ctx context.Context, ref string, gateRetries int) (kitNeeds, error) {
merged, err := l.Fetch.Assemble(ctx, []fetch.Request{{Reference: ref}}, kit.MergeOptions)
if err != nil {
return nil, kit.ImageConfig{}, fmt.Errorf("read kit: %w", err)
return kitNeeds{}, fmt.Errorf("read kit: %w", err)
}
plan, err := kit.FromMerge(merged.MergeResult)
if err != nil {
return nil, kit.ImageConfig{}, err
k := kitNeeds{}
if k.plan, err = kit.FromMerge(merged.MergeResult); err != nil {
return kitNeeds{}, err
}
img, err := l.imageConfig(ctx, ref)
if err != nil {
return nil, kit.ImageConfig{}, err
if err := kit.ValidateNeeds(k.plan, gateRetries); err != nil {
return kitNeeds{}, err
}
if k.img, err = l.imageConfig(ctx, ref); err != nil {
return kitNeeds{}, err
}
for _, name := range slices.Sorted(maps.Keys(merged.Env)) {
img.Env = append(img.Env, name+"="+merged.Env[name])
k.img.Env = append(k.img.Env, name+"="+merged.Env[name])
}
return plan, img, nil
if k.network, err = spec.NetworkPolicyOf(k.plan.Capabilities); err != nil {
return kitNeeds{}, err
}
if k.creds, err = spec.CredentialsOf(k.plan.Capabilities); err != nil {
return kitNeeds{}, err
}
if k.skills, err = spec.AgentSkillsOf(k.plan.Capabilities); err != nil {
return kitNeeds{}, err
}
return k, nil
}
// skillsDir is the operator's live skills_dir, or "" with no config.
func (l *Launcher) skillsDir() string {
if l.Config == nil {
return ""
}
return l.Config.Get().SkillsDir
}
// Release stops the run's container, then removes its network, revokes its
@@ -301,3 +320,19 @@ func (l *Launcher) imageConfig(ctx context.Context, ref string) (kit.ImageConfig
Env: slices.Clone(cfg.Env), User: cfg.User,
}, nil
}
// skillsBinds mounts the operator's shared skills store read-only at each
// path the Kit asks for it, whatever mode the Kit asks for. With no
// skills_dir configured the host withholds the mount.
func skillsBinds(asks []spec.AgentSkillsCapability, sharedDir string) []string {
if sharedDir == "" {
return nil
}
var binds []string
for _, a := range asks {
if a.Path != "" {
binds = append(binds, skill.StoreDir(sharedDir)+":"+a.Path+":ro")
}
}
return binds
}
@@ -135,3 +135,18 @@ func TestResolveCredentialsIsAnIntersection(t *testing.T) {
})
}
}
// The skills store is mounted read-only whatever mode a Kit asks for, and
// not at all when the operator configured none.
func TestSkillsBinds(t *testing.T) {
asks := []spec.AgentSkillsCapability{
{Path: "/home/agent/.claude/skills", Mode: "readwrite"},
}
got := skillsBinds(asks, "/srv/shared")
if len(got) != 1 || got[0] != "/srv/shared/.agents/skills:/home/agent/.claude/skills:ro" {
t.Fatalf("skillsBinds = %v, want the store mounted read-only at the Kit's path", got)
}
if got := skillsBinds(asks, ""); len(got) != 0 {
t.Fatalf("skillsBinds with no skills_dir = %v, want none", got)
}
}
+4
View File
@@ -162,6 +162,10 @@ func SkillForWorkflow(catalog []CatalogEntry, workflow string) *CatalogEntry {
const skillsDir = ".agents/skills"
// StoreDir is where root keeps its skills: the directory a skills store
// mounted into a harness exposes.
func StoreDir(root string) string { return filepath.Join(root, skillsDir) }
// Parse extracts YAML frontmatter and body from SKILL.md content.
// The frontmatter is delimited by "---" lines. If no frontmatter is found,
// the entire content is returned as the body with a zero Frontmatter.