Agent Workspace

┌─────────────────────────────────────────────────────────────────────┐
│  KERNEL (Authoritative)          │  MARKDOWN         │  AGENT       │
│  ─────────────────────           │  ────────         │  ─────       │
│  • System Law                    │  • AGENTS.md      │  • Reads     │
│  • Governance Engine             │  • IDENTITY.md    │  • Decides   │
│  • Policy Enforcement            │  • POLICY.md      │  • Acts      │
│  • Ledger/Receipts               │  • MEMORY.md      │  • Logs      │
│  • Context Pack Builder          │  • BRAIN.md       │  • Syncs     │
└─────────────────────────────────────────────────────────────────────┘
          ↑                           ↑                         ↑
          │                           │                         │
          └─────────── SYNC ──────────┴──────── REHYDRATE ─────┘

.allternit/skills/
├── _template/
│   ├── SKILL.md
│   └── contract.json
└── my-skill/
    ├── SKILL.md
    └── contract.json

Phase 1: System Initialization
├── Step 1: Lock acquisition
├── Step 2: Load manifest
└── Step 3: Crash recovery

Phase 2: Identity & Governance
├── Step 4: Load IDENTITY.md
├── Step 5: Load AGENTS.md (constitution)
├── Step 6: Load SOUL.md
└── Step 7: Load USER.md

Phase 3: Environment & Tools
├── Step 8: Load TOOLS.md
├── Step 9: Load SYSTEM.md
├── Step 10: Load CHANNELS.md
└── Step 11: Load POLICY.md

Phase 4: Memory Hydration
├── Step 12: Load MEMORY.md
├── Step 13: Load daily logs
├── Step 14: Load active tasks
├── Step 15: Load lessons
└── Step 16: Load self-reviews

Phase 5: Capabilities
├── Step 17: Index skills
├── Step 18: Load tool registry
└── Step 19: Load provider configs

Phase 6: Context Build
├── Step 20: Build context pack
└── Step 21: Resume work

[dependencies]
allternit-agent-workspace = "0.1.0"

use allternit_agent_workspace::initialize_workspace;
use std::path::Path;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let workspace = Path::new("./my-agent");
    let context = initialize_workspace(workspace).await?;

    println!("Agent: {}", context.agent_name());
    println!("Focus: {}", context.current_focus());

    Ok(())
}

use allternit_agent_workspace::{PolicyEngine, PolicyDecision};
use std::collections::HashMap;

let engine = PolicyEngine::from_workspace("./my-agent")?;
let args = HashMap::new();

match engine.check_tool("filesystem.delete", &args) {
    PolicyDecision::Allow => println!("Tool allowed"),
    PolicyDecision::RequireApproval(reason) => {
        println!("Approval required: {}", reason)
    }
    PolicyDecision::Deny(reason) => println!("Denied: {}", reason),
}

use allternit_agent_workspace::ContextPackBuilder;

let mut builder = ContextPackBuilder::new("./my-agent");
builder.load_identity()?;
builder.load_governance()?;
builder.load_cognitive()?;
builder.load_skills()?;
builder.build_summary()?;

let pack = builder.build()?;
println!("Context pack: {} bytes", pack.total_size_bytes());

use allternit_agent_workspace::checkpoint::{
    CheckpointManager, AgentState, TaskState,
};

let manager = CheckpointManager::new("./my-agent");
let checkpoint = manager.create(
    "session-1",
    AgentState { /* ... */ },
    TaskState { /* ... */ },
)?;

// Later, restore from the checkpoint
manager.restore(&checkpoint.id)?;

# Initialize a new workspace
allternit-workspace init --name my-agent --nature "Code Assistant"

# Boot the workspace
allternit-workspace boot

# Check workspace status
allternit-workspace status

# Check policy for a tool
allternit-workspace check filesystem.delete

# List skills
allternit-workspace skills

# Build context pack
allternit-workspace build-pack

.allternit/
├── manifest.json                # Workspace metadata
├── brain/
│   └── BRAIN.md                 # Task graph human view
├── memory/
│   ├── YYYY-MM-DD.md           # Daily session logs
│   ├── active-tasks.md         # Current task queue
│   ├── lessons.md              # Curated learnings
│   └── self-review.md          # Introspection logs
├── identity/
│   ├── IDENTITY.md             # Agent identity
│   ├── SOUL.md                 # Agent behavior
│   ├── USER.md                 # User preferences
│   ├── VOICE.md                # Voice config
│   └── POLICY.md               # Runtime overrides
├── governance/
│   ├── PLAYBOOK.md             # Procedures
│   ├── TOOLS.md                # Tool configuration
│   ├── HEARTBEAT.md            # Periodic tasks
│   ├── SYSTEM.md               # Environment constraints
│   └── CHANNELS.md             # MCP/external channels
├── skills/
│   ├── _template/              # Skill template
│   └── {skill_name}/           # Individual skills
│       ├── SKILL.md
│       └── contract.json
├── business/
│   ├── CLIENTS.md              # Client registry
│   ├── crm/                    # Contact info
│   ├── Projects/               # Project workspaces
│   └── content/                # Content templates
├── contracts/
│   ├── skills.index.json       # Skill registry index
│   └── tools.registry.json     # Tool registry
├── context/
│   └── pack.current.json       # Compiled context pack
└── state/
    ├── taskgraph.json          # Machine task graph
    ├── checkpoints.jsonl       # Session checkpoints
    └── locks/                  # Workspace locks

Kernel Ledger Receipts
         ↓
   ┌─────────────┐
   │ Sync Engine │
   └─────────────┘
         ↓
┌──────────────────┐
│ memory/*.md      │  ← Human-readable session logs
│ MEMORY.md index  │  ← Index of all memories
└──────────────────┘
         ↓
   Agent Context

# Build for std (CLI usage)
cargo build --features std

# Build WASM package for browser
cargo build --target wasm32-unknown-unknown \
  --no-default-features --features wasm --release

# Generate JS/TS bindings
wasm-bindgen target/wasm32-unknown-unknown/release/allternit_agent_workspace.wasm \
  --out-dir pkg \
  --typescript \
  --target web

import { WorkspaceApi } from '@allternit/agent-workspace';

const workspace = new WorkspaceApi('/path/to/workspace');
const result = await workspace.boot();
console.log(result);

const policyResult = workspace.checkTool('filesystem.write');
console.log(policyResult);

[kernel]
endpoint = "https://kernel.allternit.io"
workspace_id = "ws-abc123"
api_key = "${KERNEL_API_KEY}"

[sync]
auto = true
interval = 300  # 5 minutes
on_boot = true
on_shutdown = true

[sync.policies]
conflict_resolution = "ask"  # ask, local, remote, merge
policy_changes_require_approval = true