# VLCode-Lite IDE Resource Architecture

> Candidate stable Path alias: 13
> Date: 2026-04-20
> Status: Repo canonical source for Agent OS runtime/resource boundary, published as SystemDoc `IdeResourceArchitecture` v0.2

Companion docs:
- `docs/runtime-resource-consensus.md` (read this first for onboarding)
- `docs/unified-capability-layered-architecture.md`
- `docs/unified-capability-implementation-mapping.md`
- `docs/vlcode-agent-os-blueprint.md`
- `docs/vlcode-agent-node-architecture.md`
- `docs/vl-asset-logic-chain-spec.md`

## 1. Intent

Cross-product layering note:

- `docs/unified-capability-layered-architecture.md` is the canonical source for VLC vs Agent OS vs Agent App layering, namespace ownership, and runtime principal boundaries.
- This document stays focused on runtime/resource extraction and storage/control-plane boundaries.

This document defines the IDE/resource-side architecture for VLCode-Lite as an Agent OS:

- which objects are first-class resources
- how they relate to each other
- how they persist locally and in cloud/shared form
- and what it means to move the runtime out of the IDE shell without losing workflow-centric execution

The goal is to preserve the strengths that already exist in VLCode-Lite:

- actor-like execution inside workflows
- strong VL delivery depth
- artifact lineage and control-plane persistence
- rerunnable flow execution

while making the platform clearer, more local-first, and more suitable for assistant-first entry points.

## 2. What "Pull Runtime Out Of The IDE" Actually Means

The current system already has actor-like execution inside workflows. That is good and should remain.

What is missing is not "more actor nodes". What is missing is a **headless runtime host** that is independent from the IDE shell process.

### 2.1 Current Good State

Today the repository already has:

- workflow execution
- actor-step execution
- sub-agent execution
- team runtime persistence
- control-plane SQLite
- resource tree overlays

So the problem is not "actors are not running". They are.

### 2.2 Current Limitation

Right now, the lifecycle of these capabilities is still mostly attached to the IDE/server host:

- session routing is IDE-first
- tool access is mostly process-global
- permissions are soft, not hard ceilings
- remote triggers and multi-channel entry are weak
- if the IDE/web host is not present, the Agent OS is not truly always-on

### 2.3 Target Meaning

"Pull runtime out of the IDE" means:

- keep the IDE as one client surface
- move gateway, scheduler, session manager, permission guard, and control-plane ownership into a long-lived daemon/gateway
- let Web IDE, Electron, chat entry, automation entry, and future channel adapters all talk to the same runtime

So the target shape is:

```text
IDE / Electron / Web / Chat / Automation / Channel Adapter
                        |
                    Gateway
                        |
       Actor Runtime + Flow Runtime + Tool Runtime
                        |
     Control Plane + Workspace + Artifacts + Resource Store
```

This is not a rejection of workflow-bound actors.

It is a separation of:

- **surface**: where the user talks to the system
- **runtime**: where tasks, permissions, sessions, and artifacts are actually governed

## 3. Recommended First-Class Model

The cleanest model is:

| Kind | Primary Question | Responsibility |
|------|------------------|----------------|
| Actor | Who is doing the work? | Identity, domain, runtime ownership, escalation rights |
| Skill | How does this actor usually work? | Playbook, capability bundle, docs/flow/tool preferences |
| Tool | What atomic action can be executed now? | Deterministic or provider-backed execution |
| Flow | In what governed order should work happen? | Sequencing, gates, retries, reruns, state |
| Component | What reusable implementation asset can be inserted? | Reusable code/file/module payloads |
| Artifact | What evidence/output was produced? | Deliverables, reports, generated files, review packets |
| Resource | How is any of the above persisted and indexed? | Registry identity, lineage, sync, discovery |
| Pack | How is capability distributed? | Installable bundle of actors/skills/tools/flows/components/docs |

### 3.4 Storage Boundary

For the IDE/runtime boundary to stay clean, the storage split should be explicit:

- Platform specs belong to the SysDoc / Resource Center document interfaces and are cached under `~/.vl-code/`.
- Official shared workflow/skill seeds ship with the application bundle and are upgraded by the app.
- Developer-owned workflow assets live in the current workspace under `.vl-code/`.

Recommended workspace-local folders:

- `.vl-code/workflows/`
- `.vl-code/skills/`
- `.vl-code/tools/`
- `.vl-code/components/`
- `.vl-code/docs/`

Recommended rule:

> Do not mirror workflow JSON or prompt payloads back into the platform spec space.

That keeps "platform docs/specs" and "workspace workflow assets" separate in both storage and registration.

### 3.4.1 Workspace Registry Files

The runtime now treats these registry files as the canonical workspace-owned entry points:

| Resource | Workspace Registry | Notes |
|----------|--------------------|-------|
| Workflow | `.vl-code/workflows/*.json` | Runtime workflow assets live directly as JSON files |
| Skill | `.vl-code/skills/skills-registry.json` + `.vl-code/skills/*.skill.md` | Registry owns structured metadata; markdown owns the human-readable contract |
| Tool | `.vl-code/tools/_registry.json` + `.vl-code/tools/*.js` | Workspace tools are hot-loadable and can override platform-shared tools |
| Component | `.vl-code/components/components-registry.json` | Registry caches installed/reused component modules and their workspace file writes |
| Docs | `.vl-code/docs/` | Workspace-authored docs only; platform specs stay in the platform-doc home cache |

Recommended rule:

> Workspace registries are the developer-owned layer. Shared seeds should never be edited in-place.

### 3.4.2 Runtime Loader Precedence

The runtime contract should be consistent and explicit:

| Resource | Effective Precedence | Current Implementation |
|----------|----------------------|------------------------|
| Workflow | `workspace-local > platform-shared > legacy-user-home` | `.vl-code/workflows` first, bundled seed workflows second, `~/.vl-code/workflows` last |
| Skill | `workspace-local > platform-shared > legacy-user-home > builtin-legacy` | Workspace `skills-registry.json` overrides bundled `public/seed-skills`; old home skills and builtin legacy skills are compatibility layers |
| Tool | `workspace-local > platform-shared > legacy-user-home` | Workspace tool registry can override builtin/shared tools; legacy `~/.vl-code/tools` remains readable but no longer silently overrides builtin tools |
| Component | `workspace-local > platform-shared provider` | Workspace component registry is checked first; Component Factory remains the shared provider/fallback |

Special rule for skills:

> Runtime-special builtin skills such as loop-based repair flows keep their builtin execution semantics even when shared/workspace metadata overrides their display contract.

This is important because the skill catalog and the skill executor must not drift apart:

- UI should show the same effective skill/tool/component source that runtime will actually use.
- Upload/install flows should default to workspace-local storage.
- Legacy home-level storage remains compatibility-only and should be treated as deprecated, not primary.

### 3.1 Actor

An **Actor** is the first-class operating entity.

An Actor owns:

- identity
- execution domain
- communication domain
- arbitration policy
- tool view
- flow bindings
- escalation policy
- result contract

Examples:

- `assistant` as the top-level AI-Chat supervisor/router
- `pm`
- `architect`
- `frontend-dev`
- `qa`
- `release-board`
- `human-reviewer`

Important rule:

> Actor is "who", not just "which prompt".

### 3.1.1 Execution Domain

The execution domain is the actor's hard operating ceiling:

- which files it may read/write
- which variables it may see/change
- which tools it may call
- which artifacts it may emit

### 3.1.2 Communication Domain

The communication domain should be explicit in the actor manifest.

It should define at least:

- `mailbox.send`: which actors may receive direct handoff messages
- `mailbox.read`: which inbox threads this actor may read
- `sharedDocs.publish`: which shared document spaces this actor may publish into
- `sharedDocs.read`: which shared docs it may consume
- `handoffPolicy`: whether communication is plain text only or `mailbox + shared_doc_ref + artifact refs`

Recommended rule:

> Actor-to-Actor communication should default to `mailbox message + shared doc/artifact references`, not raw hidden state mutation.

### 3.1.3 Arbitration Policy

Every actor should declare who can overrule it and how escalation works.

Minimum fields:

- default authority
- supervisor list
- escalation triggers
- workflow entry for human review

Recommended default:

> AI actors are supervised, not sovereign.

### 3.2 Skill

A **Skill** should not be the Actor itself.

A Skill is better treated as an attachable operating bundle:

- working style
- preferred tools
- preferred flows
- required docs/specs
- acceptance expectations
- handoff conventions

This is the main refinement to the current proposal.

Your idea that "Skill defines who I am and what I can do" is directionally close, but for long-term clarity it is better to split it into:

- **Actor** = identity/runtime principal
- **Skill** = capability/persona/playbook mounted onto that actor

This keeps later features cleaner:

- permission governance
- actor pools
- skill marketplace
- session-specific skill overlays
- one actor mounting different skills in different projects

A practical compromise is:

> An Actor may declare default `skillRefs`, so UX still feels like "this actor comes with its own skill bundle".

### 3.3 Tool

A **Tool** is the smallest directly executable capability.

Examples:

- `WorkspaceManager`
- `WorkflowRun`
- `TeamWorkflowRuntime`
- `VLAdjust`
- `VLCompile`
- `ReadFile`
- `WriteFile`

Tool rules:

- tools are atomic
- tools declare permissions
- tools do not own project orchestration
- tools may invoke flows, but they are still leaf executors

### 3.4 Flow

A **Flow** is the durable orchestration contract.

It provides:

- node order
- graph branching
- retry/rerun checkpoints
- actor assignment
- verifier gates
- human gates
- state accumulation
- artifact registration

A Flow can contain:

- Actor nodes
- Tool nodes
- Subflow nodes
- HumanGate nodes
- Verifier nodes
- future graph patch / dispatch-await nodes

Important rule:

> Flow is not "just another tool". It is a first-class governed resource that may currently be invoked through a tool entry.

### 3.5 Component

A **Component** is a reusable implementation asset.

For VLCode-Lite, Components include more than UI widgets. They may include:

- VL component snippets
- section/service/app fragments
- non-VL helper files
- multi-file implementation templates
- compiled or pre-shaped implementation payloads from a large component library

This matches your idea of "stored compute":

> a mature component library stores past generation effort so later generation can recall, adapt, and embed it automatically.

Components are not orchestration units. They are reusable payload assets selected and embedded by Actors/Flows.

## 4. Relationship Rules

The recommended relationship model is:

1. `AI-Chat` is a top-level `Supervisor Actor`, not a special one-off shell-only concept.
2. An Actor may directly use tools for short tasks.
3. An Actor may bind to one or more default flows for complex tasks.
4. A Flow may invoke Actor nodes, Tool nodes, and Subflow nodes.
5. A Component is selected or generated during Actor/Flow execution, not treated as an actor.
6. Every meaningful output becomes an Artifact and is indexed as a Resource.
7. Every resource can be local-only, cloud-mirrored, or shared both ways.

## 5. Local-First Resource Storage

All first-class resources should support:

- self-built / self-registered
- local persistence
- optional cloud persistence
- optional team sharing

Recommended local-first storage layout:

```text
.vl-code/
  control-plane.sqlite
  registry/
    actors/
    skills/
    tools/
    flows/
    packs/
  components/
  memory/
  sync/
Process/
  Artifacts/
  Reviews/
  Release/
```

Recommended persistence split:

- filesystem stores content payloads and manifests
- control-plane SQLite stores indexing, lineage, sessions, reviews, sync cursors, and runtime state

Recommended per-resource storage policy:

- `local`
- `cloud`
- `both`

Recommended default:

> local-first, cloud-optional

This keeps the system usable without cloud binding, while still allowing share/sync when desired.

## 6. Common Manifest Shape

Every first-class resource should converge on a small shared manifest envelope.

```json
{
  "id": "assistant",
  "kind": "actor",
  "title": "AI Chat Supervisor",
  "version": "0.1.0",
  "owner": "system",
  "storagePolicy": "both",
  "visibility": "project",
  "sync": {
    "enabled": true,
    "shareable": true
  },
  "refs": [],
  "tags": ["core"],
  "lineage": {
    "source": "local",
    "derivedFrom": []
  }
}
```

Then each resource kind adds its own specific contract.

### 6.1 Actor Definition

```json
{
  "id": "assistant",
  "kind": "actor",
  "title": "AI Chat Supervisor",
  "defaultSkillRefs": ["assistant-router", "vl-delivery"],
  "toolView": ["AskUser", "WorkspaceManager", "WorkflowRun", "TeamWorkflowRuntime"],
  "flowBindings": {
    "delivery": "team-vl-enterprise-delivery",
    "adjust": "incremental-update"
  },
  "runtime": {
    "executor": "gateway",
    "sessionMode": "multi-entry"
  },
  "domain": {
    "files": ["**"],
    "artifacts": ["Process/**"],
    "permissions": {
      "network": ["sysdoc"],
      "workspaceWrite": ["Process/**"],
      "shell": false
    }
  },
  "communication": {
    "mailbox": {
      "send": ["*"],
      "read": ["*"],
      "protocol": "mailbox-thread"
    },
    "sharedDocs": {
      "publish": ["shared/**", "Process/**"],
      "read": ["*"],
      "comment": ["*"]
    },
    "handoffPolicy": {
      "defaultMode": "mailbox+shared_doc_ref",
      "requireSummary": true,
      "requireEvidenceRefs": true
    }
  },
  "arbitration": {
    "authorityMode": "human-supervised",
    "defaultAuthority": "human-arbiter",
    "supervisors": ["assistant", "human-arbiter"],
    "workflowEntry": {
      "nodeKind": "HumanGate",
      "uiSurface": "modal",
      "decisionOptions": ["approve", "reject", "request_changes", "delegate"]
    },
    "escalation": {
      "onConflict": "human_gate",
      "onPermissionGap": "human_gate",
      "onVerifierFailure": "supervisor_then_human"
    }
  }
}
```

### 6.2 Skill Definition

```json
{
  "id": "vl-delivery",
  "kind": "skill",
  "title": "VL Delivery Skill",
  "preferredFlow": "team-vl-enterprise-delivery",
  "allowedTools": ["WorkflowRun", "VLCompile", "AutoTestPipeline"],
  "docRefs": ["workflowSpec", "metaSpec"],
  "acceptance": {
    "requireCompilePass": true,
    "requireArtifactSummary": true
  }
}
```

### 6.3 Flow Definition

```json
{
  "id": "team-vl-enterprise-delivery",
  "kind": "flow",
  "nodeKinds": ["actor", "tool", "subflow", "gate", "verifier"],
  "stateStore": "control-plane",
  "rerunMode": "node-checkpoint",
  "artifactPolicy": "register-all"
}
```

## 7. Execution Contract

The runtime contract should converge on these objects:

- `ActorSession`
- `TaskTicket`
- `ResultEnvelope`
- `HumanGate`
- `VerifierCheck`
- `ResourceVersion`

Recommended execution chain:

1. User/channel enters through Gateway.
2. Gateway resolves target Actor.
3. Runtime creates `ActorSession`.
4. Runtime opens `TaskTicket`.
5. Actor chooses direct tools or a bound Flow.
6. Flow runs with gates/verifiers as needed.
7. Outputs are persisted as Artifacts + Resources.
8. Completion is sealed in a `ResultEnvelope`.

This is the missing bridge between current soft actor execution and a true actor runtime primitive.

## 8. Human Arbitration And Workflow Entry

The human entry point should be a first-class workflow concept, not an out-of-band hack.

Recommended workflow expression:

```json
{
  "id": "Gate_220_HumanDecision",
  "kind": "HumanGate",
  "title": "Approve Actor Result",
  "in": {
    "reviewTarget": "=$actorEnvelope",
    "reviewSummary": "=$actorSummary"
  },
  "ui": {
    "surface": "modal",
    "options": ["approve", "reject", "request_changes", "delegate"]
  },
  "out": {
    "$gateDecision": "=$decision",
    "$gateNote": "=$note"
  }
}
```

In product terms this means:

- workflow pauses
- a modal/review panel opens for the real human
- the human chooses approve/reject/request changes/delegate
- the result is persisted into `gate_reviews`
- downstream flow continues or reroutes based on that decision

This aligns with the current runtime direction:

- `HumanGate`
- `Pause_*`
- `gate_reviews`
- `gate_review_checks`

## 9. Governance Rules

To make the model stable, four governance rules should be enforced.

### 9.1 Session-scoped tool view

An Actor should only see tools granted by:

- actor definition
- mounted skills
- session policy
- human approval elevation

### 9.2 Bounded execution domain

An Actor may only:

- read allowed files
- write allowed files
- call allowed tools
- request allowed graph changes
- escalate to allowed actors/humans

### 9.3 Result envelope

Every actor run should return:

- summary
- outputs
- evidence refs
- artifacts
- requested follow-ups
- review status

### 9.4 Local-first audit

All meaningful execution events should persist locally before optional cloud sync.

## 10. Phased Build Plan

### Phase 1: Resource Model Unification

Deliver:

- first-class resource taxonomy
- actor/skill/tool/flow/component manifests
- path registration for this architecture doc
- local-first registry folders

Why first:

- it clarifies ownership before more runtime work is added

### Phase 2: Headless Gateway / Daemon

Deliver:

- long-lived runtime service
- IDE/Electron/Web as clients
- automation entry
- remote-safe session lifecycle

Why second:

- this is what actually moves the platform from IDE-first to assistant-first runtime hosting

### Phase 3: Hard Runtime Governance

Deliver:

- session-scoped tool views
- file/network allowlists
- permission elevation
- formal `TaskTicket` and `ResultEnvelope`
- stronger run isolation

Why third:

- without this, actor autonomy remains soft and hard to trust

### Phase 4: Pack And Component Economy

Deliver:

- pack manifest
- pack install/load lifecycle
- component cache and retrieval
- local/cloud sync policy
- shareable actor/skill/tool/flow bundles

Why fourth:

- this turns internal assets into a real platform surface

### Phase 5: Multi-Channel / Multi-Node

Deliver:

- channel adapters
- companion surfaces
- remote access
- multi-device routing
- background and always-on task handling

Why fifth:

- once the runtime is headless and governed, external surfaces become much easier to add

## 11. Immediate Architecture Decisions

This document locks in the following decisions:

1. Keep workflow-embedded actor execution. Do not throw it away.
2. Move lifecycle governance into a headless runtime/gateway over time.
3. Treat `AI-Chat` as a top-level Actor.
4. Separate `Actor` from `Skill`, while allowing Actors to mount default skills.
5. Treat `Flow` as a first-class governed resource, not only a tool payload.
6. Treat `Component` as reusable stored implementation effort, not as an actor.
7. Make all resources local-first and optionally cloud-shareable.
