Skip to content

docs: document runtime policy contract and 'mounted vs exposed' guidance #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
rovo79 wants to merge 1 commit into from
Closed

docs: document runtime policy contract and 'mounted vs exposed' guidance #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions docs/ai/ARCHITECTURE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,34 @@
- HTTP API is GET-only and does not implement auth, sessions, or protocol-level MCP envelopes.
- `features/sdkGeneration.ts` and sandbox code execution are placeholders (not production behavior yet).


## Skill guidance vs runtime authority

- Skills are declarative policy inputs (intent, preferences, constraints, escalation conditions).
- Runtime/client is the operative authority (mount/unmount, hide/show, schema filtering, phase transitions).
- The architecture seam is: `skill selection -> policy evaluation -> runtime enforcement -> narrowed visible tool universe`.

Comment on lines +50 to +55

Copilot AI Apr 21, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This new section describes a runtime/skill policy seam and enforcement responsibilities, but this file otherwise documents current server implementation details. To avoid contradicting the “reflects current implementation” positioning of these AI docs, consider adding an explicit note here that the policy contract is a draft design target and not implemented/enforced by the current checked-in runtime.

Copilot uses AI. Check for mistakes.
### Key distinction: mounted vs exposed

- **Mounted** means runtime can access a pack/server.
- **Exposed** means model can see and call tools/resources/prompts from that pack.
- Runtime should support mounted-but-hidden packs so capability access can expand only when policy conditions are met.

### Minimal runtime policy contract (draft)

- Skill contributes a declarative `mcp_policy` block with:
- `startup_packs`
- `allowed_packs`
- `default_visibility`
- `escalation` rules (for example `evidence_gap`, `docs_exhausted`)
- Runtime evaluates and enforces that contract via pack lifecycle orchestration and tool registry filtering.

### Practical implementation layers

1. **Skill layer**: triggers + policy declaration.
2. **Runtime policy layer**: evaluates policy against current phase/evidence.
3. **MCP pack manager layer**: starts/stops packs and updates model-visible registry.

## Assumptions

- Architecture description reflects current implementation, not full roadmap/RFC target state.
Expand Down
90 changes: 87 additions & 3 deletions packages/agent-runner/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,89 @@
# @driftcore/agent-runner (placeholder)
# @driftcore/agent-runner (runtime policy contract draft)

This directory intentionally provides a minimal placeholder package so CI jobs that still run `npm install --prefix packages/agent-runner` do not fail.
This package is still a lightweight placeholder, but it now documents a precise split of responsibilities between:
Comment on lines +1 to +3

Copilot AI Apr 21, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This README now serves as a policy-contract reference, but the package is still marked as a CI placeholder in package.json ("implementation is not present"). Consider adding an explicit sentence here that no agent-runner runtime/client implementation exists in this repository yet, so readers don’t interpret the contract/responsibilities sections as describing currently shipped behavior.

Copilot uses AI. Check for mistakes.

The runtime implementation of an agent runner is not currently present in this repository.
- **Skills** (declarative policy input), and
- **Agent runtime/client** (operative policy enforcement).

## Core principle

- If it says what should happen, it belongs in a **skill**.
- If it makes it happen, it belongs in the **runtime**.

Skills can express intent (preferences, constraints, escalation rules). Only runtime can attach/detach MCP servers, filter tool/resource visibility, and keep irrelevant capabilities out of model context.

## Mental model

- **MCP server/pack**: building full of tools.
- **Skill**: playbook for a job.
- **Runtime**: facilities manager with the keys.

The playbook can request access patterns; runtime enforces them.

## Runtime design target: `mounted != exposed`

Treat these as separate states:

- **Mounted**: runtime can reach the MCP pack/server.
- **Exposed**: model can see and invoke pack tools/resources/prompts.

A pack can be mounted but hidden from the model until a policy condition is satisfied.

## Minimal contract between skill and runtime

A skill should declare policy. Runtime should evaluate and enforce it.

```yaml
skill_id: drupal-audit

mcp_policy:
startup_packs:
- core.fs
- core.git

allowed_packs:
- core.fs
- core.git
- docs.php
- web.search

default_visibility: hidden

Comment on lines +39 to +51

Copilot AI Apr 21, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the example contract, default_visibility: hidden combined with startup_packs is ambiguous: are startup_packs merely mounted at startup, or also exposed initially? Later the doc suggests starting with a pack exposed by default. Please clarify the semantics (e.g., define whether startup_packs implies mounted-only, and how initial exposure is determined), or adjust the example fields to remove the ambiguity.

Copilot uses AI. Check for mistakes.
escalation:
- when: evidence_gap
expose:
- docs.php

- when: docs_exhausted
expose:
- web.search
```

## Runtime responsibilities (minimum viable)

1. **Pack registry**
- Know available pack IDs and how to start/stop each MCP server.
2. **Policy evaluator**
- Read `mcp_policy` from selected skill and compute desired mounted/exposed sets.
3. **Visibility model**
- Enforce `default_visibility`, and expose only allowed packs.
4. **Escalation engine**
- Detect conditions (`evidence_gap`, `docs_exhausted`) and apply policy transitions.
5. **Tool registry filter**
- Rebuild the model-visible tool/resource/prompt catalog whenever exposure changes.

## Suggested first proof of concept

Implement a tiny runtime loop with three packs:

- `core`
- `local-dev`
- `web-research`

Policy behavior:

1. Start with `core` only exposed.
2. On `evidence_gap`, expose `local-dev`.
3. On `docs_exhausted`, expose `web-research`.
Comment on lines +83 to +87

Copilot AI Apr 21, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The proof-of-concept pack IDs (core, local-dev, web-research) don’t match the earlier YAML example pack IDs (core.fs, core.git, docs.php, web.search). This makes it hard to map the POC steps to the contract. Align the naming between the YAML example and the POC (or add a short note explaining the two naming schemes).

Suggested change
Policy behavior:
1. Start with `core` only exposed.
2. On `evidence_gap`, expose `local-dev`.
3. On `docs_exhausted`, expose `web-research`.
Note: these are simplified POC labels. In the YAML example above, `core` stands in for the always-available local packs (`core.fs` and `core.git`), `local-dev` stands in for the documentation/dev-assist pack (`docs.php`), and `web-research` maps to `web.search`.
Policy behavior:
1. Start with `core` only exposed (`core.fs`/`core.git` in the YAML example).
2. On `evidence_gap`, expose `local-dev` (`docs.php` in the YAML example).
3. On `docs_exhausted`, expose `web-research` (`web.search` in the YAML example).

Copilot uses AI. Check for mistakes.

This validates the architecture seam before scaling policy complexity.
Loading