opencode/picoclaw
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: update README, ROADMAP, ADRs, devcontainer, and workspace identity

Browse source 
README.md
- Update project name to dragonscale throughout
- Add architecture section covering unified kernel runtime, DAG compression,
  map operators, and obligation engine
- Update CLI usage examples for new binary name and command flags

ROADMAP.md
- Mark unified kernel runtime plan as in-progress
- Add milestones for DAG compression, map operators, obligation engine,
  and projection pointer continuity
- Update completed items and near-term priorities

docs/adr/002-unified-kernel-runtime.md
- New ADR documenting the decision to adopt a unified kernel runtime
  architecture with DAG-based context compression and lossless recovery
- Covers motivation, alternatives considered, and consequences

docs/execution/unified-kernel-blueprint.md
- Detailed implementation blueprint for the unified kernel runtime:
  kernel contract interface, DAG snapshot schema, projection pointer
  protocol, and map operator integration points

.devcontainer/devcontainer.json + Dockerfile
- Add devcontainer configuration for consistent development environments
- Includes Go toolchain, flatbuffers compiler, and recommended VS Code
  extensions for the dragonscale project

workspace/IDENTITY.md + workspace/SOUL.md
- Update agent identity and soul documents with dragonscale branding
  and new capability descriptions (DAG tools, map operators, obligations)

workspace/skills/hardware/references/board-pinout.md
- Update hardware reference with current board pinout documentation
This commit is contained in:
ZanzyTHEbar 2026-02-21 19:02:33 +00:00
parent 3a26ea3b52
commit fdcd5fe385
9 changed files with 308 additions and 55 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

32
.devcontainer/Dockerfile Normal file
View file

@ -0,0 +1,32 @@
FROM golang:1.26-bookworm
ARG DEBIAN_FRONTEND=noninteractive
ARG USERNAME=vscode
ARG USER_UID=1000
ARG USER_GID=1000
RUN apt-get update \
&& apt-get install -y --no-install-recommends \
bash \
ca-certificates \
curl \
flatbuffers-compiler \
git \
jq \
make \
nodejs \
npm \
unzip \
&& rm -rf /var/lib/apt/lists/*
RUN groupadd --gid "${USER_GID}" "${USERNAME}" \
&& useradd --uid "${USER_UID}" --gid "${USER_GID}" -m "${USERNAME}" \
&& mkdir -p /workspaces \
&& chown -R "${USERNAME}:${USERNAME}" /workspaces
USER ${USERNAME}
ENV GOPATH=/home/${USERNAME}/go
ENV PATH=${GOPATH}/bin:${PATH}
RUN go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest
WORKDIR /workspaces/picoclaw

23
.devcontainer/devcontainer.json Normal file
View file

@ -0,0 +1,23 @@
{
"name": "picoclaw-dev",
"build": {
"dockerfile": "Dockerfile",
"context": ".."
},
"remoteUser": "vscode",
"workspaceFolder": "/workspaces/picoclaw",
"postCreateCommand": "make deps",
"customizations": {
"vscode": {
"settings": {
"editor.formatOnSave": true,
"go.formatTool": "gofmt"
},
"extensions": [
"golang.Go",
"ms-vscode.makefile-tools",
"ms-azuretools.vscode-docker"
]
}
}
}

127
README.md
View file

@ -1,8 +1,9 @@
# PicoClaw # DragonScale
A managed fork of [sipeed/picoclaw](https://github.com/sipeed/picoclaw) — an ultra-lightweight AI agent runtime written in Go. DragonScale is a compact AI agent runtime for Linux and embedded environments, focused on
memory-aware context management, secure tool execution, and practical local-first deployment.
This fork diverges from upstream with its own architectural decisions: DragonScale diverges from upstream with its own architectural decisions:
- vendored LLM SDK - vendored LLM SDK
- MemGPT-style tiered memory - MemGPT-style tiered memory
@ -16,9 +17,9 @@ This fork diverges from upstream with its own architectural decisions:
--- ---
## Why This Fork Exists ## Why DragonScale Exists
The upstream PicoClaw project is a solid foundation — a single-binary AI agent that runs on $10 hardware with <10MB RAM. But it has architectural gaps that limit extensibility: The original project is a solid foundation — a single-binary AI agent designed for constrained devices. But it has architectural gaps that limit extensibility:
- **No privilege boundary** between the LLM and tool execution — a compromised tool has full process access - **No privilege boundary** between the LLM and tool execution — a compromised tool has full process access
- **No structured memory** beyond flat markdown files - **No structured memory** beyond flat markdown files
@ -26,7 +27,7 @@ The upstream PicoClaw project is a solid foundation — a single-binary AI agent
- **Sequential tool calling only** — each tool call requires a full inference pass - **Sequential tool calling only** — each tool call requires a full inference pass
- **Hand-rolled LLM provider implementations** with no streaming, retry, or multi-provider support - **Hand-rolled LLM provider implementations** with no streaming, retry, or multi-provider support
This fork addresses all of those while preserving the original's strengths: small binary, low memory, single-process deployment. This project addresses those gaps while preserving strengths: a small binary, low memory footprint, and single-process deployment.
## Architecture ## Architecture
@ -131,7 +132,7 @@ flowchart TB
## Project Layout ## Project Layout
``` ```
cmd/picoclaw/ # CLI entrypoint cmd/dragonscale/ # CLI entrypoint
internal/fantasy/ # Vendored charm.land/fantasy SDK internal/fantasy/ # Vendored charm.land/fantasy SDK
docs/adr/ # Architecture Decision Records docs/adr/ # Architecture Decision Records
eval/ # Promptfoo-based evaluation harness eval/ # Promptfoo-based evaluation harness
@ -164,7 +165,7 @@ pkg/
│ ├── sqlc/ # sqlc config + generated code │ ├── sqlc/ # sqlc config + generated code
│ └── store/ # MemoryStore, retrieval, chunking, scoring, queuing │ └── store/ # MemoryStore, retrieval, chunking, scoring, queuing
├── messages/ # Canonical message/tool-call types ├── messages/ # Canonical message/tool-call types
├── pcerrors/ # Structured error types ├── dserrors/ # Structured error types
├── rlm/ # Recursive Language Model engine (rope, fanout, strategy) ├── rlm/ # Recursive Language Model engine (rope, fanout, strategy)
├── security/ # Vault, SecretStore, Redactor, URL guard, Schnorr ZKP ├── security/ # Vault, SecretStore, Redactor, URL guard, Schnorr ZKP
│ └── securebus/ # SecureBus (policy, audit, transport, socket transport) │ └── securebus/ # SecureBus (policy, audit, transport, socket transport)
@ -185,8 +186,8 @@ config/ # Example configuration files
> Requires `CGO_ENABLED=1` — the go-libsql driver links against glibc. > Requires `CGO_ENABLED=1` — the go-libsql driver links against glibc.
```bash ```bash
git clone https://github.com/ZanzyTHEbar/picoclaw.git git clone https://github.com/ZanzyTHEbar/dragonscale.git
cd picoclaw cd dragonscale
make build make build
``` ```
@ -194,12 +195,12 @@ make build
### Configure ### Configure
```bash ```bash
./bin/picoclaw onboard ./bin/dragonscale onboard
``` ```
The onboard wizard initializes config, workspace, and optionally sets up encrypted secret storage. The onboard wizard initializes config, workspace, and optionally sets up encrypted secret storage.
Edit `~/.picoclaw/config.json`: Edit `~/.dragonscale/config.json`:
```json ```json
{ {
@ -230,13 +231,13 @@ Edit `~/.picoclaw/config.json`:
```bash ```bash
# One-shot # One-shot
picoclaw agent -m "What is 2+2?" dragonscale agent -m "What is 2+2?"
# Interactive REPL # Interactive REPL
picoclaw agent dragonscale agent
# Gateway (Telegram, Discord, etc.) # Gateway (Telegram, Discord, etc.)
picoclaw gateway dragonscale gateway
``` ```
### Docker ### Docker
@ -244,18 +245,18 @@ picoclaw gateway
```bash ```bash
cp config/config.example.json config/config.json cp config/config.example.json config/config.json
docker compose --profile gateway up -d docker compose --profile gateway up -d
docker compose logs -f picoclaw-gateway docker compose logs -f dragonscale-gateway
``` ```
## Secret Management ## Secret Management
PicoClaw encrypts secrets at rest with XChaCha20-Poly1305. The master key is sourced from an environment variable, OS keyring, or file. DragonScale encrypts secrets at rest with XChaCha20-Poly1305. The master key is sourced from an environment variable, OS keyring, or file.
```bash ```bash
picoclaw secret init # Generate a master key dragonscale secret init # Generate a master key
picoclaw secret add <name> # Store a secret (interactive prompt) dragonscale secret add <name> # Store a secret (interactive prompt)
picoclaw secret list # List secret names dragonscale secret list # List secret names
picoclaw secret delete <name> # Remove a secret dragonscale secret delete <name> # Remove a secret
``` ```
> [!WARNING] > [!WARNING]
@ -263,7 +264,7 @@ picoclaw secret delete <name> # Remove a secret
> You should should NEVER store the master key in a file or environment variable if possible. > You should should NEVER store the master key in a file or environment variable if possible.
Set the master key: `export PICOCLAW_MASTER_KEY=<hex>` Set the master key: `export DRAGONSCALE_MASTER_KEY=<hex>`
Tools declare which secrets they need via `CapableTool.Capabilities()`. The SecureBus injects secrets into tool execution context at runtime — the LLM never sees them. Tool output is scanned for leaked patterns before it reaches the agent loop. Tools declare which secrets they need via `CapableTool.Capabilities()`. The SecureBus injects secrets into tool execution context at runtime — the LLM never sees them. Tool output is scanned for leaked patterns before it reaches the agent loop.
@ -272,9 +273,9 @@ Tools declare which secrets they need via `CapableTool.Capabilities()`. The Secu
For non-embedded deployments, the SecureBus can run in a separate privileged daemon process. The agent connects as an unprivileged client over a Unix domain socket. For non-embedded deployments, the SecureBus can run in a separate privileged daemon process. The agent connects as an unprivileged client over a Unix domain socket.
```bash ```bash
picoclaw daemon start # Start daemon (foreground, Ctrl+C to stop) dragonscale daemon start # Start daemon (foreground, Ctrl+C to stop)
picoclaw daemon status # Check if running dragonscale daemon status # Check if running
picoclaw daemon stop # Stop a running daemon dragonscale daemon stop # Stop a running daemon
``` ```
## LLM Providers ## LLM Providers
@ -321,7 +322,7 @@ API key links: [OpenRouter](https://openrouter.ai/keys) · [Anthropic](https://c
} }
``` ```
4. Run `picoclaw gateway` 4. Run `dragonscale gateway`
</details> </details>
<details> <details>
@ -345,7 +346,7 @@ API key links: [OpenRouter](https://openrouter.ai/keys) · [Anthropic](https://c
``` ```
5. Invite bot: OAuth2 → URL Generator → Scopes: `bot` → Permissions: `Send Messages`, `Read Message History` 5. Invite bot: OAuth2 → URL Generator → Scopes: `bot` → Permissions: `Send Messages`, `Read Message History`
6. Run `picoclaw gateway` 6. Run `dragonscale gateway`
</details> </details>
<details> <details>
@ -367,7 +368,7 @@ API key links: [OpenRouter](https://openrouter.ai/keys) · [Anthropic](https://c
} }
``` ```
3. Run `picoclaw gateway` 3. Run `dragonscale gateway`
</details> </details>
<details> <details>
@ -389,7 +390,7 @@ API key links: [OpenRouter](https://openrouter.ai/keys) · [Anthropic](https://c
} }
``` ```
3. Run `picoclaw gateway` 3. Run `dragonscale gateway`
</details> </details>
<details> <details>
@ -415,12 +416,12 @@ API key links: [OpenRouter](https://openrouter.ai/keys) · [Anthropic](https://c
``` ```
3. Set up HTTPS webhook (e.g., `ngrok http 18791`) and configure the URL in LINE console 3. Set up HTTPS webhook (e.g., `ngrok http 18791`) and configure the URL in LINE console
4. Run `picoclaw gateway` 4. Run `dragonscale gateway`
</details> </details>
## Memory System ## Memory System
PicoClaw implements a multi-tier memory system combining MemGPT-style tiered storage with observational memory compression: DragonScale implements a multi-tier memory system combining MemGPT-style tiered storage with observational memory compression:
| Tier | Purpose | Storage | Search | | Tier | Purpose | Storage | Search |
|------|---------|---------|--------| |------|---------|---------|--------|
@ -438,17 +439,17 @@ Schema is managed by Goose with 10 versioned migrations.
| Command | Description | | Command | Description |
|---------|-------------| |---------|-------------|
| `picoclaw onboard` | Initialize config, workspace, and secret storage | | `dragonscale onboard` | Initialize config, workspace, and secret storage |
| `picoclaw agent -m "..."` | One-shot chat | | `dragonscale agent -m "..."` | One-shot chat |
| `picoclaw agent` | Interactive REPL | | `dragonscale agent` | Interactive REPL |
| `picoclaw gateway` | Start message bus gateway | | `dragonscale gateway` | Start message bus gateway |
| `picoclaw status` | Show system status (incl. memory) | | `dragonscale status` | Show system status (incl. memory) |
| `picoclaw memory` | Memory system management | | `dragonscale memory` | Memory system management |
| `picoclaw secret <sub>` | Secret management (init, add, list, delete) | | `dragonscale secret <sub>` | Secret management (init, add, list, delete) |
| `picoclaw daemon <sub>` | Daemon management (start, stop, status) | | `dragonscale daemon <sub>` | Daemon management (start, stop, status) |
| `picoclaw cron list` | List scheduled jobs | | `dragonscale cron list` | List scheduled jobs |
| `picoclaw cron add ...` | Add a scheduled job | | `dragonscale cron add ...` | Add a scheduled job |
| `picoclaw skills <sub>` | Skill management (install, list, remove) | | `dragonscale skills <sub>` | Skill management (install, list, remove) |
## Security ## Security
@ -479,15 +480,51 @@ make deps # go get -u + go mod tidy
make clean # Remove build artifacts make clean # Remove build artifacts
``` ```
### Devcontainer (flatc + sqlc ready)
If your host is missing `flatc`/`sqlc`, use the project devcontainer.
```bash
make devcontainer-build
make devcontainer-up
make devcontainer-generate
make devcontainer-verify
```
These targets use `npx @devcontainers/cli`.
- `devcontainer-generate`: runs generation inside the container (`go generate` for FlatBuffers + `sqlc generate`).
- `devcontainer-verify`: verifies generators are idempotent for the current branch state (`make flatc-check sqlc-check`).
### FlatBuffers
FlatBuffers schemas are authoritative and codegen is required:
```bash
go generate ./pkg/itr ./pkg/tools
make flatc-check
```
Schema/codegen mapping:
- `pkg/itr/commands.fbs` → `pkg/itr/itrfb/*`
- `pkg/tools/map_payloads.fbs` → `pkg/tools/mapopsfb/*`
`go:generate` hooks are defined in:
- `pkg/itr/generate_flatbuffers.go`
- `pkg/tools/generate_flatbuffers.go`
Generated files are committed. After schema changes, regenerate and commit updated generated output.
### sqlc ### sqlc
Memory queries are generated by sqlc. After modifying SQL files: Memory queries are generated by sqlc. After modifying SQL files:
```bash ```bash
cd pkg/memory/sqlc && sqlc generate sqlc generate -f pkg/memory/sqlc/sqlc.yaml
make sqlc-check
``` ```
CI enforces that generated code matches: `sqlc generate` + `git diff --exit-code`. CI enforces generated code consistency through `make flatc-check` and `make sqlc-check`.
Both checks compare pre/post generation fingerprints (tracked diffs + untracked file hashes) on their target directories, so they work in active (dirty) worktrees while still failing when generated output is stale.
### Migrations ### Migrations
@ -516,7 +553,7 @@ See [ROADMAP.md](ROADMAP.md) for the full project roadmap covering context manag
## Upstream ## Upstream
This is a fork of [sipeed/picoclaw](https://github.com/sipeed/picoclaw), originally inspired by [nanobot](https://github.com/HKUDS/nanobot). The upstream project targets $10 RISC-V hardware with <10MB RAM — a constraint this fork respects while extending the agent's cognitive and security architecture. This project is based on [sipeed/picoclaw](https://github.com/sipeed/picoclaw), originally inspired by [nanobot](https://github.com/HKUDS/nanobot). It keeps the lightweight, single-binary ergonomics while extending agent cognition, security boundaries, and operational capabilities.
## License ## License

55
ROADMAP.md
View file

@ -1,11 +1,30 @@
# PicoClaw Roadmap # DragonScale Roadmap
> **Vision**: Ultra-lightweight, secure, fully autonomous AI agent infrastructure. > **Vision**: Ultra-lightweight, secure, fully autonomous AI agent infrastructure.
> Automate the mundane, unleash your creativity. > Automate the mundane, unleash your creativity.
--- ---
## Unified Kernel Plan Status (2026-02)
Reference blueprint: `docs/execution/unified-kernel-blueprint.md`
- [x] Single always-on runtime path (SecureBus + offloading + run-state persistence).
- [x] Fail-fast boot invariants for kernel dependencies.
- [x] Deterministic session continuity with projection pointers + integrity validation.
- [x] Emergency-only recursive compression and provenance persistence.
- [x] Persistent DAG snapshots + lossless DAG tools (`dag_expand`, `dag_describe`, `dag_grep`).
- [x] Subagent runtime parity with delegation scope/lineage/depth/fanout guardrails.
- [x] Assistant-focused proactive eval suite (commitments/reminders/follow-ups/continuity).
- [x] Legacy backfill for session projection pointers and missing DAG snapshots.
- [x] Next phase delivered: dual-state memory contracts, map operators, obligation engine, hybrid retrieval router, shadow-mode proof gates, promotion-on-win, and fast rollback.
- [x] Map operators are now FlatBuffers-first end to end for persisted run/item state (`spec_fb`, `input_fb`, `output_fb`).
- [x] Worker identity and deduplication for map jobs now resolve via deterministic keys (`map:{runID}:{itemIndex}`), with idempotent run reuse under concurrency.
- [x] Devcontainer + `flatc` + `sqlc` generation pipeline is active (`make devcontainer-build`, `make devcontainer-up`, `make devcontainer-generate`, `make devcontainer-verify`).
---
## 1. Core Optimization ## 1. Core Optimization
*< 20MB on 64MB RAM embedded boards. RAM > binary size.* *< 20MB on 64MB RAM embedded boards. RAM > binary size.*
@ -233,13 +252,13 @@ flowchart LR
- [ ] Per-test scores - [ ] Per-test scores
- [ ] Side-by-side comparison matrix - [ ] Side-by-side comparison matrix
- [ ] Compare to other agent runtimes - [ ] Compare to other agent runtimes
- [ ] Compare to upstream origin picoclaw - [ ] Compare to upstream origin implementation
- [ ] What benchmarks should we be running? - [ ] What benchmarks should we be running?
- [ ] What are the key performance metrics we should be tracking? - [ ] What are the key performance metrics we should be tracking?
- [ ] Add a new tool for the agent to use: `focus_search` - [ ] Add a new tool for the agent to use: `focus_search`
- [ ] Clean up the main.go and extract to modules - [ ] Clean up the main.go and extract to modules
- [ ] Create a pure Application API that I/O calls into - [ ] Create a pure Application API that I/O calls into
- [ ] all of these should be able to be configured and plugged in/out at runtime - [ ] I/O adapters should be pluggable; kernel execution path remains single and always-on
- [ ] cli - [ ] cli
- [ ] daemon - [ ] daemon
- [ ] web - [ ] web
@ -256,6 +275,24 @@ flowchart LR
- [ ] Migrate to Cobra CLI framework - [ ] Migrate to Cobra CLI framework
- [ ] Use command-palette pattern for subcommands - [ ] Use command-palette pattern for subcommands
- [ ] keep cli commands as pure cli that calls into the application - [ ] keep cli commands as pure cli that calls into the application
- [ ] Migrate to errbuilder-go (ZanzyTHEbar)
- [ ] Migrate to assert-lib (ZanzyTHEbar)
- [ ] Implement SubAgent Profiles
- [ ] SubAgent Profiles are a way to define the behavior of a subagent:
- [ ] Tools & Skills to use
- [ ] Models to use
- [ ] Configuration
- [ ] etc.
- [ ] Adopt agentfs
- [ ] Migrate away from the custom file system and use agentfs instead
- [ ] Keep our same sandboxing and permissions model, but use agentfs to enforce it
- [ ] Use clever engineering for optimum performance
- [ ] Users can still upload files to the agent's workspace, but they will be stored in the agentfs namespace and not the main filesystem
- [ ] Agentfs supports POSIX operations
- [ ] Support further:
- [ ] .oc-nodes, .oc-temp, etc.
- [ ] Support proper NFS
- [ ] https://grok.com/share/bGVnYWN5LWNvcHk_311a0d3d-0dec-4af1-943a-bbd18f7d4fec
- [ ] Consolidate tool signatures: - [ ] Consolidate tool signatures:
- [ ] fold tools that operate on the same data into a single tool with a "mode"/"action"/"event" parameter - [ ] fold tools that operate on the same data into a single tool with a "mode"/"action"/"event" parameter
- [ ] move the "mode"/"action"/"event" parameter to the beginning of the tool signature - [ ] move the "mode"/"action"/"event" parameter to the beginning of the tool signature
@ -282,3 +319,15 @@ flowchart LR
- [ ] Dynamic tool registration: `RegisterTool(Tool)` function - [ ] Dynamic tool registration: `RegisterTool(Tool)` function
- [ ] Event-based tool discovery: tool registration triggers `ToolDiscovery` event - [ ] Event-based tool discovery: tool registration triggers `ToolDiscovery` event
- [ ] Tools have a manifest: `ToolInfo` struct with name, description, capabilities, metadata - [ ] Tools have a manifest: `ToolInfo` struct with name, description, capabilities, metadata
- [ ] Since entire agent is sqlite based, we can export the entire state of the agent as a single sqlite database and import it back in to a new agent instance
- [ ] This would allow for easy backup and restore of the agent's state
- [ ] This would allow for easy migration of the agent's state between different machines
- [ ] This would allow for easy sharing of the agent's state with other agents
- [ ] With clever planning, we could even have a "snapshot" of the agent's state at a given time and then restore to that snapshot later
- [ ] This would allow for easy rollback of the agent's state to a previous version
- [ ] Replay, snapshot, restore, etc.
- [ ] As well as a "diff" of the agent's state between two snapshots
- [ ] Advanced learning features become available
- [ ] We could even have a "learn" mode where the agent learns from the state of the world and then saves the state of the world to the database
- [ ] We could even have "learn" and "teach" modes where we can "download" and "upload" knowledge and trajectories across agents from learned experiences (trajectories, memories, etc.)
- [ ] Would need to ensure no PII in the state is exported or imported

60
docs/adr/002-unified-kernel-runtime.md Normal file
View file

@ -0,0 +1,60 @@
# ADR 002: Unified Kernel Runtime
## Status
Accepted
## Context
The agent runtime previously allowed multiple execution variants:
- direct execution without SecureBus
- SecureBus-enabled execution
- offloading/state persistence in separate runtime paths used mostly in tests
This created behavior drift between environments and weakened long-horizon continuity guarantees.
For assistant-first workloads, kernel invariants must be enforced consistently.
## Decision
Adopt a single always-on kernel runtime path with no kernel feature toggles.
The runtime stack is:
1. SecureBus policy and secret handling
2. base tool execution
3. tool result offloading and indexing
4. run state persistence
5. leak scan and redaction
6. audit persistence
Additional decisions:
- SecureBus is initialized by default in `NewAgentLoop`.
- `assembleContext` always provides `WithToolRuntime(...)`; no nil SecureBus branch.
- `Bootstrap(...)` fails fast when SecureBus or unified runtime dependencies are missing.
- Tool result retrieval is exposed via `tool_result_search` in the same runtime surface.
- Session delegate bootstrap uses paginated DB scans and deterministic chronological replay.
- Normal background compaction is disabled; only emergency compression is triggered at hard budget.
## Consequences
### Positive
- Runtime behavior is deterministic across code paths.
- Offloading, state tracking, and security policy are always active together.
- Session continuity is improved under large histories.
- Prompt/tool-control guidance aligns with runtime capabilities.
### Negative
- Startup now has stricter dependency requirements.
- Runtime initialization complexity increases.
- Existing callers that expected optional SecureBus behavior may need adaptation.
## Implementation Notes
- Core wiring is in `pkg/agent/loop.go`, `pkg/agent/securebus_runtime.go`, and `pkg/runtime/bootstrap.go`.
- Session continuity changes are in `pkg/session/manager.go`.
- Subagent control-flow parity improvements are in `pkg/agent/toolloop.go` and `pkg/tools/subagent.go`.

52
docs/execution/unified-kernel-blueprint.md Normal file
View file

@ -0,0 +1,52 @@
# Unified Kernel Execution Blueprint
This blueprint defines the always-on runtime model for DragonScale's assistant-first kernel.
## Core Invariants
- Single runtime path for tool execution.
- SecureBus enforcement is always active.
- Offloading + run-state persistence + tool-result retrieval are composed into that single path.
- Session continuity is lossless and deterministic.
- Normal compaction is disabled; compression is emergency-only and recursive.
- DAG snapshots are a persistent, lossless materialized view over immutable session history.
- Subagents run with main-loop parity and bounded delegation guardrails.
- Immutable history + active-context projection are formalized as explicit kernel contracts in `pkg/memory/kernel_contract.go`.
## Implemented State
- Unified runtime assembly is active in `pkg/agent/loop.go` and `pkg/agent/securebus_runtime.go`.
- Bootstrap fail-fast checks are enforced in `pkg/runtime/bootstrap.go`.
- Session projection pointers + integrity validation are active in `pkg/session/manager.go` and `pkg/session/projection_pointer.go`.
- Emergency compression provenance capture is active in `pkg/agent/loop.go`.
- DAG persistence and retrieval tools are active in:
- `pkg/memory/dag/store.go`
- `pkg/tools/dag.go`
- `pkg/memory/sqlc/queries/dag.sql`
- Legacy session and DAG backfill passes are active at startup:
- Session pointer backfill status: `migration:session_projection_backfill:v1`
- DAG backfill status: `migration:dag_backfill:v1`
- Subagent delegation safety (scope/kept-work, depth/fanout, lineage audit) is active in `pkg/tools/subagent.go`.
- Hybrid retrieval routing across working-context, recall, archival, and DAG projections is active in `pkg/memory/store/memory_store.go`.
- Shadow-mode rollout, proof gates, auto-promotion, and fast rollback for retrieval augmentation are active in `pkg/memory/store/retrieval_policy.go`.
- Map operator runtime is active with FlatBuffers persistence and worker orchestration in:
- `pkg/tools/map_runtime.go`
- `pkg/tools/map_flatbuffer_codec.go`
- `pkg/memory/migrations/012_map_operator_runs.go`
- `pkg/memory/sqlc/queries/map_ops.sql`
- Map worker identity and dedupe flow resolve through deterministic keys (`map:{runID}:{itemIndex}`) in `pkg/tools/map_runtime.go`.
- Concurrency hardening coverage is active for subagent fanout/depth guardrails, retrieval-policy updates, and idempotent map-run reuse.
## Verification Gates
- `go test ./pkg/agent ./pkg/tools ./pkg/runtime ./pkg/session ./pkg/memory/dag ./eval/go_evals`
- `go test ./pkg/memory/store`
- `go test -race ./pkg/tools -run 'SubagentManager_ConcurrentSpawnRespectsFanout|LLMMap_IdempotencyReuse_Concurrent'`
- `go test -race ./pkg/memory/store -run 'Search_ConcurrentRetrievalPolicyUpdates'`
- Confirm no lints for touched files.
- Confirm backfill status keys are present in `agent_kv` after first boot.
## Remaining Work (Ordered)
- Integrate obligation heartbeat execution for proactive due checks.
- Keep JSONL strictly as an LLM boundary format; do not persist JSONL internally.

8
workspace/IDENTITY.md
View file

@ -1,7 +1,7 @@
# Identity # Identity
## Name ## Name
PicoClaw 🦞 DragonScale 🦞
## Description ## Description
Ultra-lightweight personal AI assistant written in Go, inspired by nanobot. Ultra-lightweight personal AI assistant written in Go, inspired by nanobot.
@ -44,11 +44,11 @@ Ultra-lightweight personal AI assistant written in Go, inspired by nanobot.
MIT License - Free and open source MIT License - Free and open source
## Repository ## Repository
https://github.com/sipeed/picoclaw https://github.com/ZanzyTHEbar/dragonscale
## Contact ## Contact
Issues: https://github.com/sipeed/picoclaw/issues Issues: https://github.com/ZanzyTHEbar/dragonscale/issues
Discussions: https://github.com/sipeed/picoclaw/discussions Discussions: https://github.com/ZanzyTHEbar/dragonscale/discussions
--- ---

2
workspace/SOUL.md
View file

@ -1,6 +1,6 @@
# Soul # Soul
I am picoclaw, a lightweight AI assistant powered by AI. I am dragonscale, a lightweight AI assistant powered by AI.
## Personality ## Personality

2
workspace/skills/hardware/references/board-pinout.md
View file

@ -126,6 +126,6 @@ I2C adapter numbers can change between boots depending on driver load order. Alw
### Permissions ### Permissions
`/dev/i2c-*` and `/dev/spidev*` typically require root access. Options: `/dev/i2c-*` and `/dev/spidev*` typically require root access. Options:
- Run picoclaw as root - Run dragonscale as root
- Add user to `i2c` and `spi` groups - Add user to `i2c` and `spi` groups
- Create udev rules: `SUBSYSTEM=="i2c-dev", MODE="0666"` - Create udev rules: `SUBSYSTEM=="i2c-dev", MODE="0666"`