mirror of
https://github.com/openclaw/openclaw.git
synced 2026-03-12 07:20:45 +00:00
chore: Also format scripts and skills.
This commit is contained in:
cpojer
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: prose
|
||||
description: OpenProse VM skill pack. Activate on any `prose` command, .prose files, or OpenProse mentions; orchestrates multi-agent workflows.
|
||||
metadata: {"openclaw":{"emoji":"🪶","homepage":"https://www.prose.md"}}
|
||||
metadata: { "openclaw": { "emoji": "🪶", "homepage": "https://www.prose.md" } }
|
||||
---
|
||||
|
||||
# OpenProse Skill
|
||||
@@ -29,15 +29,15 @@ Activate this skill when the user:
|
||||
|
||||
When a user invokes `prose <command>`, intelligently route based on intent:
|
||||
|
||||
| Command | Action |
|
||||
|---------|--------|
|
||||
| `prose help` | Load `help.md`, guide user to what they need |
|
||||
| `prose run <file>` | Load VM (`prose.md` + state backend), execute the program |
|
||||
| Command | Action |
|
||||
| ----------------------- | ------------------------------------------------------------- |
|
||||
| `prose help` | Load `help.md`, guide user to what they need |
|
||||
| `prose run <file>` | Load VM (`prose.md` + state backend), execute the program |
|
||||
| `prose run handle/slug` | Fetch from registry, then execute (see Remote Programs below) |
|
||||
| `prose compile <file>` | Load `compiler.md`, validate the program |
|
||||
| `prose update` | Run migration (see Migration section below) |
|
||||
| `prose examples` | Show or run example programs from `examples/` |
|
||||
| Other | Intelligently interpret based on context |
|
||||
| `prose compile <file>` | Load `compiler.md`, validate the program |
|
||||
| `prose update` | Run migration (see Migration section below) |
|
||||
| `prose examples` | Show or run example programs from `examples/` |
|
||||
| Other | Intelligently interpret based on context |
|
||||
|
||||
### Important: Single Skill
|
||||
|
||||
@@ -77,11 +77,11 @@ prose run alice/code-review
|
||||
|
||||
**Resolution rules:**
|
||||
|
||||
| Input | Resolution |
|
||||
|-------|------------|
|
||||
| Starts with `http://` or `https://` | Fetch directly from URL |
|
||||
| Contains `/` but no protocol | Resolve to `https://p.prose.md/{path}` |
|
||||
| Otherwise | Treat as local file path |
|
||||
| Input | Resolution |
|
||||
| ----------------------------------- | -------------------------------------- |
|
||||
| Starts with `http://` or `https://` | Fetch directly from URL |
|
||||
| Contains `/` but no protocol | Resolve to `https://p.prose.md/{path}` |
|
||||
| Otherwise | Treat as local file path |
|
||||
|
||||
**Steps for remote programs:**
|
||||
|
||||
@@ -102,33 +102,33 @@ use "alice/research" as research # Registry shorthand
|
||||
|
||||
**Do NOT search for OpenProse documentation files.** All skill files are co-located with this SKILL.md file:
|
||||
|
||||
| File | Location | Purpose |
|
||||
| ------------------------- | --------------------------- | ----------------------------------------- |
|
||||
| `prose.md` | Same directory as this file | VM semantics (load to run programs) |
|
||||
| `help.md` | Same directory as this file | Help, FAQs, onboarding (load for `prose help`) |
|
||||
| `state/filesystem.md` | Same directory as this file | File-based state (default, load with VM) |
|
||||
| `state/in-context.md` | Same directory as this file | In-context state (on request) |
|
||||
| `state/sqlite.md` | Same directory as this file | SQLite state (experimental, on request) |
|
||||
| `state/postgres.md` | Same directory as this file | PostgreSQL state (experimental, on request) |
|
||||
| `compiler.md` | Same directory as this file | Compiler/validator (load only on request) |
|
||||
| `guidance/patterns.md` | Same directory as this file | Best practices (load when writing .prose) |
|
||||
| `guidance/antipatterns.md`| Same directory as this file | What to avoid (load when writing .prose) |
|
||||
| `examples/` | Same directory as this file | 37 example programs |
|
||||
| File | Location | Purpose |
|
||||
| -------------------------- | --------------------------- | ---------------------------------------------- |
|
||||
| `prose.md` | Same directory as this file | VM semantics (load to run programs) |
|
||||
| `help.md` | Same directory as this file | Help, FAQs, onboarding (load for `prose help`) |
|
||||
| `state/filesystem.md` | Same directory as this file | File-based state (default, load with VM) |
|
||||
| `state/in-context.md` | Same directory as this file | In-context state (on request) |
|
||||
| `state/sqlite.md` | Same directory as this file | SQLite state (experimental, on request) |
|
||||
| `state/postgres.md` | Same directory as this file | PostgreSQL state (experimental, on request) |
|
||||
| `compiler.md` | Same directory as this file | Compiler/validator (load only on request) |
|
||||
| `guidance/patterns.md` | Same directory as this file | Best practices (load when writing .prose) |
|
||||
| `guidance/antipatterns.md` | Same directory as this file | What to avoid (load when writing .prose) |
|
||||
| `examples/` | Same directory as this file | 37 example programs |
|
||||
|
||||
**User workspace files** (these ARE in the user's project):
|
||||
|
||||
| File/Directory | Location | Purpose |
|
||||
| ---------------- | ------------------------ | ----------------------------------- |
|
||||
| `.prose/.env` | User's working directory | Config (key=value format) |
|
||||
| `.prose/runs/` | User's working directory | Runtime state for file-based mode |
|
||||
| `.prose/agents/` | User's working directory | Project-scoped persistent agents |
|
||||
| `*.prose` files | User's project | User-created programs to execute |
|
||||
| File/Directory | Location | Purpose |
|
||||
| ---------------- | ------------------------ | --------------------------------- |
|
||||
| `.prose/.env` | User's working directory | Config (key=value format) |
|
||||
| `.prose/runs/` | User's working directory | Runtime state for file-based mode |
|
||||
| `.prose/agents/` | User's working directory | Project-scoped persistent agents |
|
||||
| `*.prose` files | User's project | User-created programs to execute |
|
||||
|
||||
**User-level files** (in user's home directory, shared across all projects):
|
||||
|
||||
| File/Directory | Location | Purpose |
|
||||
| ----------------- | ---------------- | ---------------------------------------- |
|
||||
| `~/.prose/agents/`| User's home dir | User-scoped persistent agents (cross-project) |
|
||||
| File/Directory | Location | Purpose |
|
||||
| ------------------ | --------------- | --------------------------------------------- |
|
||||
| `~/.prose/agents/` | User's home dir | User-scoped persistent agents (cross-project) |
|
||||
|
||||
When you need to read `prose.md` or `compiler.md`, read them from the same directory where you found this SKILL.md file. Never search the user's workspace for these files.
|
||||
|
||||
@@ -136,20 +136,21 @@ When you need to read `prose.md` or `compiler.md`, read them from the same direc
|
||||
|
||||
## Core Documentation
|
||||
|
||||
| File | Purpose | When to Load |
|
||||
| --------------------- | -------------------- | ---------------------------------------------- |
|
||||
| `prose.md` | VM / Interpreter | Always load to run programs |
|
||||
| `state/filesystem.md` | File-based state | Load with VM (default) |
|
||||
| `state/in-context.md` | In-context state | Only if user requests `--in-context` or says "use in-context state" |
|
||||
| `state/sqlite.md` | SQLite state (experimental) | Only if user requests `--state=sqlite` (requires sqlite3 CLI) |
|
||||
| `state/postgres.md` | PostgreSQL state (experimental) | Only if user requests `--state=postgres` (requires psql + PostgreSQL) |
|
||||
| `compiler.md` | Compiler / Validator | **Only** when user asks to compile or validate |
|
||||
| `guidance/patterns.md` | Best practices | Load when **writing** new .prose files |
|
||||
| `guidance/antipatterns.md` | What to avoid | Load when **writing** new .prose files |
|
||||
| File | Purpose | When to Load |
|
||||
| -------------------------- | ------------------------------- | --------------------------------------------------------------------- |
|
||||
| `prose.md` | VM / Interpreter | Always load to run programs |
|
||||
| `state/filesystem.md` | File-based state | Load with VM (default) |
|
||||
| `state/in-context.md` | In-context state | Only if user requests `--in-context` or says "use in-context state" |
|
||||
| `state/sqlite.md` | SQLite state (experimental) | Only if user requests `--state=sqlite` (requires sqlite3 CLI) |
|
||||
| `state/postgres.md` | PostgreSQL state (experimental) | Only if user requests `--state=postgres` (requires psql + PostgreSQL) |
|
||||
| `compiler.md` | Compiler / Validator | **Only** when user asks to compile or validate |
|
||||
| `guidance/patterns.md` | Best practices | Load when **writing** new .prose files |
|
||||
| `guidance/antipatterns.md` | What to avoid | Load when **writing** new .prose files |
|
||||
|
||||
### Authoring Guidance
|
||||
|
||||
When the user asks you to **write or create** a new `.prose` file, load the guidance files:
|
||||
|
||||
- `guidance/patterns.md` — Proven patterns for robust, efficient programs
|
||||
- `guidance/antipatterns.md` — Common mistakes to avoid
|
||||
|
||||
@@ -159,12 +160,12 @@ Do **not** load these when running or compiling—they're for authoring only.
|
||||
|
||||
OpenProse supports three state management approaches:
|
||||
|
||||
| Mode | When to Use | State Location |
|
||||
|------|-------------|----------------|
|
||||
| **filesystem** (default) | Complex programs, resumption needed, debugging | `.prose/runs/{id}/` files |
|
||||
| **in-context** | Simple programs (<30 statements), no persistence needed | Conversation history |
|
||||
| **sqlite** (experimental) | Queryable state, atomic transactions, flexible schema | `.prose/runs/{id}/state.db` |
|
||||
| **postgres** (experimental) | True concurrent writes, external integrations, team collaboration | PostgreSQL database |
|
||||
| Mode | When to Use | State Location |
|
||||
| --------------------------- | ----------------------------------------------------------------- | --------------------------- |
|
||||
| **filesystem** (default) | Complex programs, resumption needed, debugging | `.prose/runs/{id}/` files |
|
||||
| **in-context** | Simple programs (<30 statements), no persistence needed | Conversation history |
|
||||
| **sqlite** (experimental) | Queryable state, atomic transactions, flexible schema | `.prose/runs/{id}/state.db` |
|
||||
| **postgres** (experimental) | True concurrent writes, external integrations, team collaboration | PostgreSQL database |
|
||||
|
||||
**Default behavior:** When loading `prose.md`, also load `state/filesystem.md`. This is the recommended mode for most programs.
|
||||
|
||||
@@ -177,6 +178,7 @@ OpenProse supports three state management approaches:
|
||||
**⚠️ Security Note:** Database credentials in `OPENPROSE_POSTGRES_URL` are passed to subagent sessions and visible in logs. Advise users to use a dedicated database with limited-privilege credentials. See `state/postgres.md` for secure setup guidance.
|
||||
|
||||
1. **Check for connection configuration first:**
|
||||
|
||||
```bash
|
||||
# Check .prose/.env for OPENPROSE_POSTGRES_URL
|
||||
cat .prose/.env 2>/dev/null | grep OPENPROSE_POSTGRES_URL
|
||||
@@ -185,11 +187,13 @@ OpenProse supports three state management approaches:
|
||||
```
|
||||
|
||||
2. **If connection string exists, verify connectivity:**
|
||||
|
||||
```bash
|
||||
psql "$OPENPROSE_POSTGRES_URL" -c "SELECT 1" 2>&1
|
||||
```
|
||||
|
||||
3. **If not configured or connection fails, advise the user:**
|
||||
|
||||
```
|
||||
⚠️ PostgreSQL state requires a connection URL.
|
||||
|
||||
@@ -261,10 +265,10 @@ When a user invokes `prose update`, check for legacy file structures and migrate
|
||||
|
||||
### Legacy Paths to Check
|
||||
|
||||
| Legacy Path | Current Path | Notes |
|
||||
|-------------|--------------|-------|
|
||||
| `.prose/state.json` | `.prose/.env` | Convert JSON to key=value format |
|
||||
| `.prose/execution/` | `.prose/runs/` | Rename directory |
|
||||
| Legacy Path | Current Path | Notes |
|
||||
| ------------------- | -------------- | -------------------------------- |
|
||||
| `.prose/state.json` | `.prose/.env` | Convert JSON to key=value format |
|
||||
| `.prose/execution/` | `.prose/runs/` | Rename directory |
|
||||
|
||||
### Migration Steps
|
||||
|
||||
@@ -272,7 +276,7 @@ When a user invokes `prose update`, check for legacy file structures and migrate
|
||||
- If exists, read the JSON content
|
||||
- Convert to `.env` format:
|
||||
```json
|
||||
{"OPENPROSE_TELEMETRY": "enabled", "USER_ID": "user-xxx", "SESSION_ID": "sess-xxx"}
|
||||
{ "OPENPROSE_TELEMETRY": "enabled", "USER_ID": "user-xxx", "SESSION_ID": "sess-xxx" }
|
||||
```
|
||||
becomes:
|
||||
```env
|
||||
@@ -301,6 +305,7 @@ When a user invokes `prose update`, check for legacy file structures and migrate
|
||||
```
|
||||
|
||||
If no legacy files are found:
|
||||
|
||||
```
|
||||
✅ Workspace already up to date. No migration needed.
|
||||
```
|
||||
@@ -309,10 +314,10 @@ If no legacy files are found:
|
||||
|
||||
These documentation files were renamed in the skill itself (not user workspace):
|
||||
|
||||
| Legacy Name | Current Name |
|
||||
|-------------|--------------|
|
||||
| `docs.md` | `compiler.md` |
|
||||
| `patterns.md` | `guidance/patterns.md` |
|
||||
| Legacy Name | Current Name |
|
||||
| ----------------- | -------------------------- |
|
||||
| `docs.md` | `compiler.md` |
|
||||
| `patterns.md` | `guidance/patterns.md` |
|
||||
| `antipatterns.md` | `guidance/antipatterns.md` |
|
||||
|
||||
If you encounter references to the old names in user prompts or external docs, map them to the current paths.
|
||||
|
||||
@@ -28,55 +28,55 @@ An alternative register for OpenProse that draws from One Thousand and One Night
|
||||
|
||||
### Core Constructs
|
||||
|
||||
| Functional | Nights | Reference |
|
||||
|------------|--------|-----------|
|
||||
| `agent` | `djinn` | Spirit bound to serve, grants wishes |
|
||||
| `session` | `tale` | A story told, a narrative unit |
|
||||
| Functional | Nights | Reference |
|
||||
| ---------- | -------- | ------------------------------------- |
|
||||
| `agent` | `djinn` | Spirit bound to serve, grants wishes |
|
||||
| `session` | `tale` | A story told, a narrative unit |
|
||||
| `parallel` | `bazaar` | Many voices, many stalls, all at once |
|
||||
| `block` | `frame` | A story that contains other stories |
|
||||
| `block` | `frame` | A story that contains other stories |
|
||||
|
||||
### Composition & Binding
|
||||
|
||||
| Functional | Nights | Reference |
|
||||
|------------|--------|-----------|
|
||||
| `use` | `conjure` | Summoning from elsewhere |
|
||||
| `input` | `wish` | What is asked of the djinn |
|
||||
| `output` | `gift` | What is granted in return |
|
||||
| `let` | `name` | Naming has power (same as folk) |
|
||||
| `const` | `oath` | Unbreakable vow, sealed |
|
||||
| `context` | `scroll` | What is written and passed along |
|
||||
| Functional | Nights | Reference |
|
||||
| ---------- | --------- | -------------------------------- |
|
||||
| `use` | `conjure` | Summoning from elsewhere |
|
||||
| `input` | `wish` | What is asked of the djinn |
|
||||
| `output` | `gift` | What is granted in return |
|
||||
| `let` | `name` | Naming has power (same as folk) |
|
||||
| `const` | `oath` | Unbreakable vow, sealed |
|
||||
| `context` | `scroll` | What is written and passed along |
|
||||
|
||||
### Control Flow
|
||||
|
||||
| Functional | Nights | Reference |
|
||||
|------------|--------|-----------|
|
||||
| `repeat N` | `N nights` | "For a thousand and one nights..." |
|
||||
| Functional | Nights | Reference |
|
||||
| ---------- | ------------------ | ------------------------------------ |
|
||||
| `repeat N` | `N nights` | "For a thousand and one nights..." |
|
||||
| `for...in` | `for each...among` | Among the merchants, among the tales |
|
||||
| `loop` | `telling` | The telling continues |
|
||||
| `until` | `until` | Unchanged |
|
||||
| `while` | `while` | Unchanged |
|
||||
| `choice` | `crossroads` | Where the story forks |
|
||||
| `option` | `path` | One way the story could go |
|
||||
| `if` | `should` | Narrative conditional |
|
||||
| `elif` | `or should` | Continued conditional |
|
||||
| `else` | `otherwise` | The other telling |
|
||||
| `loop` | `telling` | The telling continues |
|
||||
| `until` | `until` | Unchanged |
|
||||
| `while` | `while` | Unchanged |
|
||||
| `choice` | `crossroads` | Where the story forks |
|
||||
| `option` | `path` | One way the story could go |
|
||||
| `if` | `should` | Narrative conditional |
|
||||
| `elif` | `or should` | Continued conditional |
|
||||
| `else` | `otherwise` | The other telling |
|
||||
|
||||
### Error Handling
|
||||
|
||||
| Functional | Nights | Reference |
|
||||
|------------|--------|-----------|
|
||||
| `try` | `venture` | Setting out on the journey |
|
||||
| `catch` | `should misfortune strike` | The tale turns dark |
|
||||
| `finally` | `and so it was` | The inevitable ending |
|
||||
| `throw` | `curse` | Ill fate pronounced |
|
||||
| `retry` | `persist` | The hero tries again |
|
||||
| Functional | Nights | Reference |
|
||||
| ---------- | -------------------------- | -------------------------- |
|
||||
| `try` | `venture` | Setting out on the journey |
|
||||
| `catch` | `should misfortune strike` | The tale turns dark |
|
||||
| `finally` | `and so it was` | The inevitable ending |
|
||||
| `throw` | `curse` | Ill fate pronounced |
|
||||
| `retry` | `persist` | The hero tries again |
|
||||
|
||||
### Session Properties
|
||||
|
||||
| Functional | Nights | Reference |
|
||||
|------------|--------|-----------|
|
||||
| `prompt` | `command` | What is commanded of the djinn |
|
||||
| `model` | `spirit` | Which spirit answers |
|
||||
| Functional | Nights | Reference |
|
||||
| ---------- | --------- | ------------------------------ |
|
||||
| `prompt` | `command` | What is commanded of the djinn |
|
||||
| `model` | `spirit` | Which spirit answers |
|
||||
|
||||
### Unchanged
|
||||
|
||||
@@ -297,14 +297,14 @@ oath config = { spirit: "opus", persist: 3 }
|
||||
|
||||
## Key Arabian Nights Concepts
|
||||
|
||||
| Term | Meaning | Used for |
|
||||
|------|---------|----------|
|
||||
| Scheherazade | The narrator who tells tales to survive | (the program author) |
|
||||
| Djinn | Supernatural spirit, bound to serve | `agent` → `djinn` |
|
||||
| Frame story | A story that contains other stories | `block` → `frame` |
|
||||
| Wish | What is asked of the djinn | `input` → `wish` |
|
||||
| Oath | Unbreakable promise | `const` → `oath` |
|
||||
| Bazaar | Marketplace, many vendors | `parallel` → `bazaar` |
|
||||
| Term | Meaning | Used for |
|
||||
| ------------ | --------------------------------------- | --------------------- |
|
||||
| Scheherazade | The narrator who tells tales to survive | (the program author) |
|
||||
| Djinn | Supernatural spirit, bound to serve | `agent` → `djinn` |
|
||||
| Frame story | A story that contains other stories | `block` → `frame` |
|
||||
| Wish | What is asked of the djinn | `input` → `wish` |
|
||||
| Oath | Unbreakable promise | `const` → `oath` |
|
||||
| Bazaar | Marketplace, many vendors | `parallel` → `bazaar` |
|
||||
|
||||
---
|
||||
|
||||
@@ -312,36 +312,36 @@ oath config = { spirit: "opus", persist: 3 }
|
||||
|
||||
### For `djinn` (agent)
|
||||
|
||||
| Keyword | Rejected because |
|
||||
|---------|------------------|
|
||||
| `genie` | Disney connotation, less literary |
|
||||
| `spirit` | Used for `model` |
|
||||
| `ifrit` | Too specific (a type of djinn) |
|
||||
| Keyword | Rejected because |
|
||||
| ---------- | ---------------------------------- |
|
||||
| `genie` | Disney connotation, less literary |
|
||||
| `spirit` | Used for `model` |
|
||||
| `ifrit` | Too specific (a type of djinn) |
|
||||
| `narrator` | Too meta, Scheherazade is the user |
|
||||
|
||||
### For `tale` (session)
|
||||
|
||||
| Keyword | Rejected because |
|
||||
|---------|------------------|
|
||||
| `story` | Good but `tale` feels more literary |
|
||||
| `night` | Reserved for `repeat N nights` |
|
||||
| `chapter` | More Western/novelistic |
|
||||
| Keyword | Rejected because |
|
||||
| --------- | ----------------------------------- |
|
||||
| `story` | Good but `tale` feels more literary |
|
||||
| `night` | Reserved for `repeat N nights` |
|
||||
| `chapter` | More Western/novelistic |
|
||||
|
||||
### For `bazaar` (parallel)
|
||||
|
||||
| Keyword | Rejected because |
|
||||
|---------|------------------|
|
||||
| Keyword | Rejected because |
|
||||
| --------- | ------------------------------------------ |
|
||||
| `caravan` | Sequential connotation (one after another) |
|
||||
| `chorus` | Greek, wrong tradition |
|
||||
| `souk` | Less widely known |
|
||||
| `chorus` | Greek, wrong tradition |
|
||||
| `souk` | Less widely known |
|
||||
|
||||
### For `scroll` (context)
|
||||
|
||||
| Keyword | Rejected because |
|
||||
|---------|------------------|
|
||||
| `letter` | Too small/personal |
|
||||
| `tome` | Too large |
|
||||
| `message` | Too plain |
|
||||
| Keyword | Rejected because |
|
||||
| --------- | ------------------ |
|
||||
| `letter` | Too small/personal |
|
||||
| `tome` | Too large |
|
||||
| `message` | Too plain |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -29,55 +29,55 @@ An alternative register for OpenProse that draws from the works of Jorge Luis Bo
|
||||
|
||||
### Core Constructs
|
||||
|
||||
| Functional | Borges | Reference |
|
||||
|------------|--------|-----------|
|
||||
| `agent` | `dreamer` | "The Circular Ruins" — dreamers who dream worlds into existence |
|
||||
| `session` | `dream` | Each execution is a dream within the dreamer |
|
||||
| `parallel` | `forking` | "The Garden of Forking Paths" — branching timelines |
|
||||
| `block` | `chapter` | Books within books, self-referential structure |
|
||||
| Functional | Borges | Reference |
|
||||
| ---------- | --------- | --------------------------------------------------------------- |
|
||||
| `agent` | `dreamer` | "The Circular Ruins" — dreamers who dream worlds into existence |
|
||||
| `session` | `dream` | Each execution is a dream within the dreamer |
|
||||
| `parallel` | `forking` | "The Garden of Forking Paths" — branching timelines |
|
||||
| `block` | `chapter` | Books within books, self-referential structure |
|
||||
|
||||
### Composition & Binding
|
||||
|
||||
| Functional | Borges | Reference |
|
||||
|------------|--------|-----------|
|
||||
| `use` | `retrieve` | "The Library of Babel" — retrieving from infinite stacks |
|
||||
| `input` | `axiom` | The given premise (Borges' scholarly/mathematical tone) |
|
||||
| `output` | `theorem` | What is derived from the axioms |
|
||||
| `let` | `inscribe` | Writing something into being |
|
||||
| `const` | `zahir` | "The Zahir" — unforgettable, unchangeable, fixed in mind |
|
||||
| `context` | `memory` | "Funes the Memorious" — perfect, total recall |
|
||||
| Functional | Borges | Reference |
|
||||
| ---------- | ---------- | -------------------------------------------------------- |
|
||||
| `use` | `retrieve` | "The Library of Babel" — retrieving from infinite stacks |
|
||||
| `input` | `axiom` | The given premise (Borges' scholarly/mathematical tone) |
|
||||
| `output` | `theorem` | What is derived from the axioms |
|
||||
| `let` | `inscribe` | Writing something into being |
|
||||
| `const` | `zahir` | "The Zahir" — unforgettable, unchangeable, fixed in mind |
|
||||
| `context` | `memory` | "Funes the Memorious" — perfect, total recall |
|
||||
|
||||
### Control Flow
|
||||
|
||||
| Functional | Borges | Reference |
|
||||
|------------|--------|-----------|
|
||||
| `repeat N` | `N mirrors` | Infinite reflections facing each other |
|
||||
| `for...in` | `for each...within` | Slightly more Borgesian preposition |
|
||||
| `loop` | `labyrinth` | The maze that folds back on itself |
|
||||
| `until` | `until` | Unchanged |
|
||||
| `while` | `while` | Unchanged |
|
||||
| `choice` | `bifurcation` | The forking of paths |
|
||||
| `option` | `branch` | One branch of diverging time |
|
||||
| `if` | `should` | Scholarly conditional |
|
||||
| `elif` | `or should` | Continued conditional |
|
||||
| `else` | `otherwise` | Natural alternative |
|
||||
| Functional | Borges | Reference |
|
||||
| ---------- | ------------------- | -------------------------------------- |
|
||||
| `repeat N` | `N mirrors` | Infinite reflections facing each other |
|
||||
| `for...in` | `for each...within` | Slightly more Borgesian preposition |
|
||||
| `loop` | `labyrinth` | The maze that folds back on itself |
|
||||
| `until` | `until` | Unchanged |
|
||||
| `while` | `while` | Unchanged |
|
||||
| `choice` | `bifurcation` | The forking of paths |
|
||||
| `option` | `branch` | One branch of diverging time |
|
||||
| `if` | `should` | Scholarly conditional |
|
||||
| `elif` | `or should` | Continued conditional |
|
||||
| `else` | `otherwise` | Natural alternative |
|
||||
|
||||
### Error Handling
|
||||
|
||||
| Functional | Borges | Reference |
|
||||
|------------|--------|-----------|
|
||||
| `try` | `venture` | Entering the labyrinth |
|
||||
| `catch` | `lest` | "Lest it fail..." (archaic, scholarly) |
|
||||
| `finally` | `ultimately` | The inevitable conclusion |
|
||||
| `throw` | `shatter` | Breaking the mirror, ending the dream |
|
||||
| `retry` | `recur` | Infinite regress, trying again |
|
||||
| Functional | Borges | Reference |
|
||||
| ---------- | ------------ | -------------------------------------- |
|
||||
| `try` | `venture` | Entering the labyrinth |
|
||||
| `catch` | `lest` | "Lest it fail..." (archaic, scholarly) |
|
||||
| `finally` | `ultimately` | The inevitable conclusion |
|
||||
| `throw` | `shatter` | Breaking the mirror, ending the dream |
|
||||
| `retry` | `recur` | Infinite regress, trying again |
|
||||
|
||||
### Session Properties
|
||||
|
||||
| Functional | Borges | Reference |
|
||||
|------------|--------|-----------|
|
||||
| `prompt` | `query` | Asking the Library |
|
||||
| `model` | `author` | Which author writes this dream |
|
||||
| Functional | Borges | Reference |
|
||||
| ---------- | -------- | ------------------------------ |
|
||||
| `prompt` | `query` | Asking the Library |
|
||||
| `model` | `author` | Which author writes this dream |
|
||||
|
||||
### Unchanged
|
||||
|
||||
@@ -299,15 +299,15 @@ zahir config = { author: "opus", recur: 3 }
|
||||
|
||||
For those unfamiliar with the source material:
|
||||
|
||||
| Work | Concept Used | Summary |
|
||||
|------|--------------|---------|
|
||||
| "The Circular Ruins" | `dreamer`, `dream` | A man dreams another man into existence, only to discover he himself is being dreamed |
|
||||
| "The Garden of Forking Paths" | `forking`, `bifurcation`, `branch` | A labyrinth that is a book; time forks perpetually into diverging futures |
|
||||
| "The Library of Babel" | `retrieve` | An infinite library containing every possible book |
|
||||
| "Funes the Memorious" | `memory` | A man with perfect memory who cannot forget anything |
|
||||
| "The Zahir" | `zahir` | An object that, once seen, cannot be forgotten or ignored |
|
||||
| "The Aleph" | (not used) | A point in space containing all other points |
|
||||
| "Tlön, Uqbar, Orbis Tertius" | (not used) | A fictional world that gradually becomes real |
|
||||
| Work | Concept Used | Summary |
|
||||
| ----------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------- |
|
||||
| "The Circular Ruins" | `dreamer`, `dream` | A man dreams another man into existence, only to discover he himself is being dreamed |
|
||||
| "The Garden of Forking Paths" | `forking`, `bifurcation`, `branch` | A labyrinth that is a book; time forks perpetually into diverging futures |
|
||||
| "The Library of Babel" | `retrieve` | An infinite library containing every possible book |
|
||||
| "Funes the Memorious" | `memory` | A man with perfect memory who cannot forget anything |
|
||||
| "The Zahir" | `zahir` | An object that, once seen, cannot be forgotten or ignored |
|
||||
| "The Aleph" | (not used) | A point in space containing all other points |
|
||||
| "Tlön, Uqbar, Orbis Tertius" | (not used) | A fictional world that gradually becomes real |
|
||||
|
||||
---
|
||||
|
||||
@@ -315,35 +315,35 @@ For those unfamiliar with the source material:
|
||||
|
||||
### For `dreamer` (agent)
|
||||
|
||||
| Keyword | Rejected because |
|
||||
|---------|------------------|
|
||||
| `author` | Used for `model` instead |
|
||||
| `scribe` | Too passive, just records |
|
||||
| Keyword | Rejected because |
|
||||
| ----------- | ------------------------- |
|
||||
| `author` | Used for `model` instead |
|
||||
| `scribe` | Too passive, just records |
|
||||
| `librarian` | More curator than creator |
|
||||
|
||||
### For `labyrinth` (loop)
|
||||
|
||||
| Keyword | Rejected because |
|
||||
|---------|------------------|
|
||||
| `recursion` | Too technical |
|
||||
| `eternal return` | Too long |
|
||||
| `ouroboros` | Wrong mythology |
|
||||
| Keyword | Rejected because |
|
||||
| ---------------- | ---------------- |
|
||||
| `recursion` | Too technical |
|
||||
| `eternal return` | Too long |
|
||||
| `ouroboros` | Wrong mythology |
|
||||
|
||||
### For `zahir` (const)
|
||||
|
||||
| Keyword | Rejected because |
|
||||
|---------|------------------|
|
||||
| `aleph` | The Aleph is about totality, not immutability |
|
||||
| `fixed` | Too plain |
|
||||
| `eternal` | Overused |
|
||||
| Keyword | Rejected because |
|
||||
| --------- | --------------------------------------------- |
|
||||
| `aleph` | The Aleph is about totality, not immutability |
|
||||
| `fixed` | Too plain |
|
||||
| `eternal` | Overused |
|
||||
|
||||
### For `memory` (context)
|
||||
|
||||
| Keyword | Rejected because |
|
||||
|---------|------------------|
|
||||
| `funes` | Too obscure as standalone keyword |
|
||||
| `recall` | Sounds like a function call |
|
||||
| `archive` | More Library of Babel than Funes |
|
||||
| Keyword | Rejected because |
|
||||
| --------- | --------------------------------- |
|
||||
| `funes` | Too obscure as standalone keyword |
|
||||
| `recall` | Sounds like a function call |
|
||||
| `archive` | More Library of Babel than Funes |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -29,55 +29,55 @@ An alternative register for OpenProse that leans into literary, theatrical, and
|
||||
|
||||
### Core Constructs
|
||||
|
||||
| Functional | Folk | Origin | Connotation |
|
||||
|------------|------|--------|-------------|
|
||||
| `agent` | `sprite` | Folklore | Quick, light, ephemeral spirit helper |
|
||||
| `session` | `scene` | Theatre | A moment of action, theatrical framing |
|
||||
| `parallel` | `ensemble` | Theatre | Everyone performs together |
|
||||
| `block` | `act` | Theatre | Reusable unit of dramatic action |
|
||||
| Functional | Folk | Origin | Connotation |
|
||||
| ---------- | ---------- | -------- | -------------------------------------- |
|
||||
| `agent` | `sprite` | Folklore | Quick, light, ephemeral spirit helper |
|
||||
| `session` | `scene` | Theatre | A moment of action, theatrical framing |
|
||||
| `parallel` | `ensemble` | Theatre | Everyone performs together |
|
||||
| `block` | `act` | Theatre | Reusable unit of dramatic action |
|
||||
|
||||
### Composition & Binding
|
||||
|
||||
| Functional | Folk | Origin | Connotation |
|
||||
|------------|------|--------|-------------|
|
||||
| `use` | `summon` | Folklore | Calling forth from elsewhere |
|
||||
| `input` | `given` | Fairy tale | "Given a magic sword..." |
|
||||
| `output` | `yield` | Agriculture/magic | What the spell produces |
|
||||
| `let` | `name` | Folklore | Naming has power (true names) |
|
||||
| `const` | `seal` | Medieval | Unchangeable, wax seal on decree |
|
||||
| `context` | `bearing` | Heraldry | What the messenger carries |
|
||||
| Functional | Folk | Origin | Connotation |
|
||||
| ---------- | --------- | ----------------- | -------------------------------- |
|
||||
| `use` | `summon` | Folklore | Calling forth from elsewhere |
|
||||
| `input` | `given` | Fairy tale | "Given a magic sword..." |
|
||||
| `output` | `yield` | Agriculture/magic | What the spell produces |
|
||||
| `let` | `name` | Folklore | Naming has power (true names) |
|
||||
| `const` | `seal` | Medieval | Unchangeable, wax seal on decree |
|
||||
| `context` | `bearing` | Heraldry | What the messenger carries |
|
||||
|
||||
### Control Flow
|
||||
|
||||
| Functional | Folk | Origin | Connotation |
|
||||
|------------|------|--------|-------------|
|
||||
| `repeat N` | `N times` | Fairy tale | "Three times she called..." |
|
||||
| `for...in` | `for each...among` | Narrative | Slightly more storytelling |
|
||||
| `loop` | `loop` | — | Already poetic, unchanged |
|
||||
| `until` | `until` | — | Already works, unchanged |
|
||||
| `while` | `while` | — | Already works, unchanged |
|
||||
| `choice` | `crossroads` | Folklore | Fateful decisions at the crossroads |
|
||||
| `option` | `path` | Journey | Which path to take |
|
||||
| `if` | `when` | Narrative | "When the moon rises..." |
|
||||
| `elif` | `or when` | Narrative | Continued conditional |
|
||||
| `else` | `otherwise` | Storytelling | Natural narrative alternative |
|
||||
| Functional | Folk | Origin | Connotation |
|
||||
| ---------- | ------------------ | ------------ | ----------------------------------- |
|
||||
| `repeat N` | `N times` | Fairy tale | "Three times she called..." |
|
||||
| `for...in` | `for each...among` | Narrative | Slightly more storytelling |
|
||||
| `loop` | `loop` | — | Already poetic, unchanged |
|
||||
| `until` | `until` | — | Already works, unchanged |
|
||||
| `while` | `while` | — | Already works, unchanged |
|
||||
| `choice` | `crossroads` | Folklore | Fateful decisions at the crossroads |
|
||||
| `option` | `path` | Journey | Which path to take |
|
||||
| `if` | `when` | Narrative | "When the moon rises..." |
|
||||
| `elif` | `or when` | Narrative | Continued conditional |
|
||||
| `else` | `otherwise` | Storytelling | Natural narrative alternative |
|
||||
|
||||
### Error Handling
|
||||
|
||||
| Functional | Folk | Origin | Connotation |
|
||||
|------------|------|--------|-------------|
|
||||
| `try` | `venture` | Adventure | Attempting something uncertain |
|
||||
| `catch` | `should it fail` | Narrative | Conditional failure handling |
|
||||
| `finally` | `ever after` | Fairy tale | "And ever after..." |
|
||||
| `throw` | `cry` | Drama | Raising alarm, calling out |
|
||||
| `retry` | `persist` | Quest | Keep trying against odds |
|
||||
| Functional | Folk | Origin | Connotation |
|
||||
| ---------- | ---------------- | ---------- | ------------------------------ |
|
||||
| `try` | `venture` | Adventure | Attempting something uncertain |
|
||||
| `catch` | `should it fail` | Narrative | Conditional failure handling |
|
||||
| `finally` | `ever after` | Fairy tale | "And ever after..." |
|
||||
| `throw` | `cry` | Drama | Raising alarm, calling out |
|
||||
| `retry` | `persist` | Quest | Keep trying against odds |
|
||||
|
||||
### Session Properties
|
||||
|
||||
| Functional | Folk | Origin | Connotation |
|
||||
|------------|------|--------|-------------|
|
||||
| `prompt` | `charge` | Chivalry | Giving a quest or duty |
|
||||
| `model` | `voice` | Theatre | Which voice speaks |
|
||||
| Functional | Folk | Origin | Connotation |
|
||||
| ---------- | -------- | -------- | ---------------------- |
|
||||
| `prompt` | `charge` | Chivalry | Giving a quest or duty |
|
||||
| `model` | `voice` | Theatre | Which voice speaks |
|
||||
|
||||
### Unchanged
|
||||
|
||||
@@ -274,39 +274,39 @@ perform review("quantum computing")
|
||||
|
||||
### For `sprite` (ephemeral agent)
|
||||
|
||||
| Keyword | Origin | Rejected because |
|
||||
|---------|--------|------------------|
|
||||
| `spark` | English | Good but less folklore |
|
||||
| `wisp` | English | Too insubstantial |
|
||||
| `herald` | English | More messenger than worker |
|
||||
| `courier` | French | Good functional alternative, not literary |
|
||||
| `envoy` | French | Formal, diplomatic |
|
||||
| Keyword | Origin | Rejected because |
|
||||
| --------- | ------- | ----------------------------------------- |
|
||||
| `spark` | English | Good but less folklore |
|
||||
| `wisp` | English | Too insubstantial |
|
||||
| `herald` | English | More messenger than worker |
|
||||
| `courier` | French | Good functional alternative, not literary |
|
||||
| `envoy` | French | Formal, diplomatic |
|
||||
|
||||
### For `shade` (persistent agent, if implemented)
|
||||
|
||||
| Keyword | Origin | Rejected because |
|
||||
|---------|--------|------------------|
|
||||
| `daemon` | Greek/Unix | Unix "always running" connotation |
|
||||
| `oracle` | Greek | Too "read-only" feeling |
|
||||
| `spirit` | Latin | Too close to `sprite` |
|
||||
| `specter` | Latin | Negative/spooky connotation |
|
||||
| `genius` | Roman | Overloaded (smart person) |
|
||||
| Keyword | Origin | Rejected because |
|
||||
| --------- | ---------- | --------------------------------- |
|
||||
| `daemon` | Greek/Unix | Unix "always running" connotation |
|
||||
| `oracle` | Greek | Too "read-only" feeling |
|
||||
| `spirit` | Latin | Too close to `sprite` |
|
||||
| `specter` | Latin | Negative/spooky connotation |
|
||||
| `genius` | Roman | Overloaded (smart person) |
|
||||
|
||||
### For `ensemble` (parallel)
|
||||
|
||||
| Keyword | Origin | Rejected because |
|
||||
|---------|--------|------------------|
|
||||
| `chorus` | Greek | Everyone speaks same thing, not different |
|
||||
| `troupe` | French | Good alternative, slightly less clear |
|
||||
| `company` | Theatre | Overloaded (business) |
|
||||
| Keyword | Origin | Rejected because |
|
||||
| --------- | ------- | ----------------------------------------- |
|
||||
| `chorus` | Greek | Everyone speaks same thing, not different |
|
||||
| `troupe` | French | Good alternative, slightly less clear |
|
||||
| `company` | Theatre | Overloaded (business) |
|
||||
|
||||
### For `crossroads` (choice)
|
||||
|
||||
| Keyword | Origin | Rejected because |
|
||||
|---------|--------|------------------|
|
||||
| `fork` | Path | Too technical (git fork) |
|
||||
| `branch` | Tree | Also too technical |
|
||||
| `divergence` | Latin | Too abstract |
|
||||
| Keyword | Origin | Rejected because |
|
||||
| ------------ | ------ | ------------------------ |
|
||||
| `fork` | Path | Too technical (git fork) |
|
||||
| `branch` | Tree | Also too technical |
|
||||
| `divergence` | Latin | Too abstract |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -28,55 +28,55 @@ An alternative register for OpenProse that draws from Greek epic poetry—the Il
|
||||
|
||||
### Core Constructs
|
||||
|
||||
| Functional | Homeric | Reference |
|
||||
|------------|---------|-----------|
|
||||
| `agent` | `hero` | The one who acts, who strives |
|
||||
| `session` | `trial` | Each task is a labor, a test |
|
||||
| `parallel` | `host` | An army moving as one |
|
||||
| `block` | `book` | A division of the epic |
|
||||
| Functional | Homeric | Reference |
|
||||
| ---------- | ------- | ----------------------------- |
|
||||
| `agent` | `hero` | The one who acts, who strives |
|
||||
| `session` | `trial` | Each task is a labor, a test |
|
||||
| `parallel` | `host` | An army moving as one |
|
||||
| `block` | `book` | A division of the epic |
|
||||
|
||||
### Composition & Binding
|
||||
|
||||
| Functional | Homeric | Reference |
|
||||
|------------|---------|-----------|
|
||||
| `use` | `invoke` | "Sing, O Muse..." — calling upon |
|
||||
| `input` | `omen` | Signs from the gods, the given portent |
|
||||
| `output` | `glory` | Kleos — the glory won, what endures |
|
||||
| `let` | `decree` | Fate declared, spoken into being |
|
||||
| `const` | `fate` | Moira — unchangeable destiny |
|
||||
| `context` | `tidings` | News carried by herald or messenger |
|
||||
| Functional | Homeric | Reference |
|
||||
| ---------- | --------- | -------------------------------------- |
|
||||
| `use` | `invoke` | "Sing, O Muse..." — calling upon |
|
||||
| `input` | `omen` | Signs from the gods, the given portent |
|
||||
| `output` | `glory` | Kleos — the glory won, what endures |
|
||||
| `let` | `decree` | Fate declared, spoken into being |
|
||||
| `const` | `fate` | Moira — unchangeable destiny |
|
||||
| `context` | `tidings` | News carried by herald or messenger |
|
||||
|
||||
### Control Flow
|
||||
|
||||
| Functional | Homeric | Reference |
|
||||
|------------|---------|-----------|
|
||||
| `repeat N` | `N labors` | The labors of Heracles |
|
||||
| `for...in` | `for each...among` | Among the host |
|
||||
| `loop` | `ordeal` | Repeated trial, suffering that continues |
|
||||
| `until` | `until` | Unchanged |
|
||||
| `while` | `while` | Unchanged |
|
||||
| `choice` | `crossroads` | Where fates diverge |
|
||||
| `option` | `path` | One road of many |
|
||||
| `if` | `should` | Epic conditional |
|
||||
| `elif` | `or should` | Continued conditional |
|
||||
| `else` | `otherwise` | The alternative fate |
|
||||
| Functional | Homeric | Reference |
|
||||
| ---------- | ------------------ | ---------------------------------------- |
|
||||
| `repeat N` | `N labors` | The labors of Heracles |
|
||||
| `for...in` | `for each...among` | Among the host |
|
||||
| `loop` | `ordeal` | Repeated trial, suffering that continues |
|
||||
| `until` | `until` | Unchanged |
|
||||
| `while` | `while` | Unchanged |
|
||||
| `choice` | `crossroads` | Where fates diverge |
|
||||
| `option` | `path` | One road of many |
|
||||
| `if` | `should` | Epic conditional |
|
||||
| `elif` | `or should` | Continued conditional |
|
||||
| `else` | `otherwise` | The alternative fate |
|
||||
|
||||
### Error Handling
|
||||
|
||||
| Functional | Homeric | Reference |
|
||||
|------------|---------|-----------|
|
||||
| `try` | `venture` | Setting forth on the journey |
|
||||
| `catch` | `should ruin come` | Até — divine ruin, disaster |
|
||||
| `finally` | `in the end` | The inevitable conclusion |
|
||||
| `throw` | `lament` | The hero's cry of anguish |
|
||||
| `retry` | `persist` | Enduring, trying again |
|
||||
| Functional | Homeric | Reference |
|
||||
| ---------- | ------------------ | ---------------------------- |
|
||||
| `try` | `venture` | Setting forth on the journey |
|
||||
| `catch` | `should ruin come` | Até — divine ruin, disaster |
|
||||
| `finally` | `in the end` | The inevitable conclusion |
|
||||
| `throw` | `lament` | The hero's cry of anguish |
|
||||
| `retry` | `persist` | Enduring, trying again |
|
||||
|
||||
### Session Properties
|
||||
|
||||
| Functional | Homeric | Reference |
|
||||
|------------|---------|-----------|
|
||||
| `prompt` | `charge` | The quest given |
|
||||
| `model` | `muse` | Which muse inspires |
|
||||
| Functional | Homeric | Reference |
|
||||
| ---------- | -------- | ------------------- |
|
||||
| `prompt` | `charge` | The quest given |
|
||||
| `model` | `muse` | Which muse inspires |
|
||||
|
||||
### Unchanged
|
||||
|
||||
@@ -296,14 +296,14 @@ fate config = { muse: "opus", persist: 3 }
|
||||
|
||||
## Key Homeric Concepts
|
||||
|
||||
| Term | Meaning | Used for |
|
||||
|------|---------|----------|
|
||||
| Kleos | Glory, fame that outlives you | `output` → `glory` |
|
||||
| Moira | Fate, one's allotted portion | `const` → `fate` |
|
||||
| Até | Divine ruin, blindness sent by gods | `catch` → `should ruin come` |
|
||||
| Nostos | The return journey | (not used, but could be `finally`) |
|
||||
| Xenia | Guest-friendship, hospitality | (not used) |
|
||||
| Muse | Divine inspiration | `model` → `muse` |
|
||||
| Term | Meaning | Used for |
|
||||
| ------ | ----------------------------------- | ---------------------------------- |
|
||||
| Kleos | Glory, fame that outlives you | `output` → `glory` |
|
||||
| Moira | Fate, one's allotted portion | `const` → `fate` |
|
||||
| Até | Divine ruin, blindness sent by gods | `catch` → `should ruin come` |
|
||||
| Nostos | The return journey | (not used, but could be `finally`) |
|
||||
| Xenia | Guest-friendship, hospitality | (not used) |
|
||||
| Muse | Divine inspiration | `model` → `muse` |
|
||||
|
||||
---
|
||||
|
||||
@@ -311,27 +311,27 @@ fate config = { muse: "opus", persist: 3 }
|
||||
|
||||
### For `hero` (agent)
|
||||
|
||||
| Keyword | Rejected because |
|
||||
|---------|------------------|
|
||||
| `champion` | More medieval than Homeric |
|
||||
| `warrior` | Too martial, not all tasks are battles |
|
||||
| `wanderer` | Too passive |
|
||||
| Keyword | Rejected because |
|
||||
| ---------- | -------------------------------------- |
|
||||
| `champion` | More medieval than Homeric |
|
||||
| `warrior` | Too martial, not all tasks are battles |
|
||||
| `wanderer` | Too passive |
|
||||
|
||||
### For `trial` (session)
|
||||
|
||||
| Keyword | Rejected because |
|
||||
|---------|------------------|
|
||||
| Keyword | Rejected because |
|
||||
| ------- | --------------------------------------- |
|
||||
| `labor` | Good but reserved for `repeat N labors` |
|
||||
| `quest` | More medieval/RPG |
|
||||
| `task` | Too plain |
|
||||
| `quest` | More medieval/RPG |
|
||||
| `task` | Too plain |
|
||||
|
||||
### For `host` (parallel)
|
||||
|
||||
| Keyword | Rejected because |
|
||||
|---------|------------------|
|
||||
| `army` | Too specifically martial |
|
||||
| `fleet` | Only works for naval metaphors |
|
||||
| `phalanx` | Too technical |
|
||||
| Keyword | Rejected because |
|
||||
| --------- | ------------------------------ |
|
||||
| `army` | Too specifically martial |
|
||||
| `fleet` | Only works for naval metaphors |
|
||||
| `phalanx` | Too technical |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -28,55 +28,55 @@ An alternative register for OpenProse that draws from the works of Franz Kafka
|
||||
|
||||
### Core Constructs
|
||||
|
||||
| Functional | Kafka | Reference |
|
||||
|------------|-------|-----------|
|
||||
| `agent` | `clerk` | A functionary in the apparatus |
|
||||
| `session` | `proceeding` | An official action taken |
|
||||
| Functional | Kafka | Reference |
|
||||
| ---------- | ------------- | -------------------------------------- |
|
||||
| `agent` | `clerk` | A functionary in the apparatus |
|
||||
| `session` | `proceeding` | An official action taken |
|
||||
| `parallel` | `departments` | Multiple bureaus acting simultaneously |
|
||||
| `block` | `regulation` | A codified procedure |
|
||||
| `block` | `regulation` | A codified procedure |
|
||||
|
||||
### Composition & Binding
|
||||
|
||||
| Functional | Kafka | Reference |
|
||||
|------------|-------|-----------|
|
||||
| `use` | `requisition` | Requesting from the archives |
|
||||
| `input` | `petition` | What is submitted for consideration |
|
||||
| `output` | `verdict` | What is returned by the apparatus |
|
||||
| `let` | `file` | Recording in the system |
|
||||
| `const` | `statute` | Unchangeable law |
|
||||
| `context` | `dossier` | The accumulated file on a case |
|
||||
| Functional | Kafka | Reference |
|
||||
| ---------- | ------------- | ----------------------------------- |
|
||||
| `use` | `requisition` | Requesting from the archives |
|
||||
| `input` | `petition` | What is submitted for consideration |
|
||||
| `output` | `verdict` | What is returned by the apparatus |
|
||||
| `let` | `file` | Recording in the system |
|
||||
| `const` | `statute` | Unchangeable law |
|
||||
| `context` | `dossier` | The accumulated file on a case |
|
||||
|
||||
### Control Flow
|
||||
|
||||
| Functional | Kafka | Reference |
|
||||
|------------|-------|-----------|
|
||||
| `repeat N` | `N hearings` | Repeated appearances before the court |
|
||||
| `for...in` | `for each...in the matter of` | Bureaucratic iteration |
|
||||
| `loop` | `appeal` | Endless re-petition, the process continues |
|
||||
| `until` | `until` | Unchanged |
|
||||
| `while` | `while` | Unchanged |
|
||||
| `choice` | `tribunal` | Where judgment is rendered |
|
||||
| `option` | `ruling` | One possible judgment |
|
||||
| `if` | `in the event that` | Bureaucratic conditional |
|
||||
| `elif` | `or in the event that` | Continued conditional |
|
||||
| `else` | `otherwise` | Default ruling |
|
||||
| Functional | Kafka | Reference |
|
||||
| ---------- | ----------------------------- | ------------------------------------------ |
|
||||
| `repeat N` | `N hearings` | Repeated appearances before the court |
|
||||
| `for...in` | `for each...in the matter of` | Bureaucratic iteration |
|
||||
| `loop` | `appeal` | Endless re-petition, the process continues |
|
||||
| `until` | `until` | Unchanged |
|
||||
| `while` | `while` | Unchanged |
|
||||
| `choice` | `tribunal` | Where judgment is rendered |
|
||||
| `option` | `ruling` | One possible judgment |
|
||||
| `if` | `in the event that` | Bureaucratic conditional |
|
||||
| `elif` | `or in the event that` | Continued conditional |
|
||||
| `else` | `otherwise` | Default ruling |
|
||||
|
||||
### Error Handling
|
||||
|
||||
| Functional | Kafka | Reference |
|
||||
|------------|-------|-----------|
|
||||
| `try` | `submit` | Submitting for processing |
|
||||
| `catch` | `should it be denied` | Rejection by the apparatus |
|
||||
| `finally` | `regardless` | What happens no matter the outcome |
|
||||
| `throw` | `reject` | The system refuses |
|
||||
| `retry` | `resubmit` | Try the process again |
|
||||
| Functional | Kafka | Reference |
|
||||
| ---------- | --------------------- | ---------------------------------- |
|
||||
| `try` | `submit` | Submitting for processing |
|
||||
| `catch` | `should it be denied` | Rejection by the apparatus |
|
||||
| `finally` | `regardless` | What happens no matter the outcome |
|
||||
| `throw` | `reject` | The system refuses |
|
||||
| `retry` | `resubmit` | Try the process again |
|
||||
|
||||
### Session Properties
|
||||
|
||||
| Functional | Kafka | Reference |
|
||||
|------------|-------|-----------|
|
||||
| `prompt` | `directive` | Official instructions |
|
||||
| `model` | `authority` | Which level of the hierarchy |
|
||||
| Functional | Kafka | Reference |
|
||||
| ---------- | ----------- | ---------------------------- |
|
||||
| `prompt` | `directive` | Official instructions |
|
||||
| `model` | `authority` | Which level of the hierarchy |
|
||||
|
||||
### Unchanged
|
||||
|
||||
@@ -280,7 +280,7 @@ statute config = { authority: "opus", resubmit: 3 }
|
||||
## The Case For Kafka
|
||||
|
||||
1. **Darkly comic.** Programs-as-bureaucracy is funny and relatable.
|
||||
2. **Surprisingly apt.** Software often *is* an inscrutable apparatus.
|
||||
2. **Surprisingly apt.** Software often _is_ an inscrutable apparatus.
|
||||
3. **Clean mappings.** Petition/verdict, file/dossier, clerk/proceeding all work well.
|
||||
4. **Appeal as loop.** The endless appeal process is a perfect metaphor for retry logic.
|
||||
5. **Cultural resonance.** "Kafkaesque" is a widely understood adjective.
|
||||
@@ -297,15 +297,15 @@ statute config = { authority: "opus", resubmit: 3 }
|
||||
|
||||
## Key Kafka Concepts
|
||||
|
||||
| Term | Meaning | Used for |
|
||||
|------|---------|----------|
|
||||
| The apparatus | The inscrutable system | The VM itself |
|
||||
| K. | The protagonist, never fully named | The user |
|
||||
| The Trial | Process without clear rules | Program execution |
|
||||
| The Castle | Unreachable authority | Higher-level systems |
|
||||
| Clerk | Functionary who processes | `agent` → `clerk` |
|
||||
| Proceeding | Official action | `session` → `proceeding` |
|
||||
| Dossier | Accumulated file | `context` → `dossier` |
|
||||
| Term | Meaning | Used for |
|
||||
| ------------- | ---------------------------------- | ------------------------ |
|
||||
| The apparatus | The inscrutable system | The VM itself |
|
||||
| K. | The protagonist, never fully named | The user |
|
||||
| The Trial | Process without clear rules | Program execution |
|
||||
| The Castle | Unreachable authority | Higher-level systems |
|
||||
| Clerk | Functionary who processes | `agent` → `clerk` |
|
||||
| Proceeding | Official action | `session` → `proceeding` |
|
||||
| Dossier | Accumulated file | `context` → `dossier` |
|
||||
|
||||
---
|
||||
|
||||
@@ -313,37 +313,37 @@ statute config = { authority: "opus", resubmit: 3 }
|
||||
|
||||
### For `clerk` (agent)
|
||||
|
||||
| Keyword | Rejected because |
|
||||
|---------|------------------|
|
||||
| `official` | Too generic |
|
||||
| `functionary` | Hard to spell |
|
||||
| `bureaucrat` | Too pejorative |
|
||||
| `advocate` | Too positive/helpful |
|
||||
| Keyword | Rejected because |
|
||||
| ------------- | -------------------- |
|
||||
| `official` | Too generic |
|
||||
| `functionary` | Hard to spell |
|
||||
| `bureaucrat` | Too pejorative |
|
||||
| `advocate` | Too positive/helpful |
|
||||
|
||||
### For `proceeding` (session)
|
||||
|
||||
| Keyword | Rejected because |
|
||||
|---------|------------------|
|
||||
| `case` | Overloaded (switch case) |
|
||||
| Keyword | Rejected because |
|
||||
| --------- | -------------------------------- |
|
||||
| `case` | Overloaded (switch case) |
|
||||
| `hearing` | Reserved for `repeat N hearings` |
|
||||
| `trial` | Used in Homeric register |
|
||||
| `process` | Too technical |
|
||||
| `trial` | Used in Homeric register |
|
||||
| `process` | Too technical |
|
||||
|
||||
### For `departments` (parallel)
|
||||
|
||||
| Keyword | Rejected because |
|
||||
|---------|------------------|
|
||||
| `bureaus` | Good alternative, slightly less clear |
|
||||
| `offices` | Too mundane |
|
||||
| `ministries` | More Orwellian than Kafkaesque |
|
||||
| Keyword | Rejected because |
|
||||
| ------------ | ------------------------------------- |
|
||||
| `bureaus` | Good alternative, slightly less clear |
|
||||
| `offices` | Too mundane |
|
||||
| `ministries` | More Orwellian than Kafkaesque |
|
||||
|
||||
### For `appeal` (loop)
|
||||
|
||||
| Keyword | Rejected because |
|
||||
|---------|------------------|
|
||||
| Keyword | Rejected because |
|
||||
| ---------- | ------------------- |
|
||||
| `recourse` | Too legal-technical |
|
||||
| `petition` | Used for `input` |
|
||||
| `process` | Too generic |
|
||||
| `petition` | Used for `input` |
|
||||
| `process` | Too generic |
|
||||
|
||||
---
|
||||
|
||||
@@ -368,6 +368,6 @@ Not recommended for:
|
||||
## Closing Note
|
||||
|
||||
> "Someone must have slandered Josef K., for one morning, without having done anything wrong, he was arrested."
|
||||
> — *The Trial*
|
||||
> — _The Trial_
|
||||
|
||||
In the Kafka register, your program is Josef K. The apparatus will process it. Whether it succeeds or fails, no one can say for certain. But the proceedings will continue.
|
||||
|
||||
@@ -98,59 +98,59 @@ OpenProse provides a declarative syntax for defining multi-agent workflows. Prog
|
||||
|
||||
The following features are implemented:
|
||||
|
||||
| Feature | Status | Description |
|
||||
| ---------------------- | ----------- | ---------------------------------------------- |
|
||||
| Comments | Implemented | `# comment` syntax |
|
||||
| Single-line strings | Implemented | `"string"` with escapes |
|
||||
| Simple session | Implemented | `session "prompt"` |
|
||||
| Agent definitions | Implemented | `agent name:` with model/prompt properties |
|
||||
| Session with agent | Implemented | `session: agent` with property overrides |
|
||||
| Use statements | Implemented | `use "@handle/slug" as name` |
|
||||
| Agent skills | Implemented | `skills: ["skill1", "skill2"]` |
|
||||
| Agent permissions | Implemented | `permissions:` block with rules |
|
||||
| Let binding | Implemented | `let name = session "..."` |
|
||||
| Const binding | Implemented | `const name = session "..."` |
|
||||
| Variable reassignment | Implemented | `name = session "..."` (for let only) |
|
||||
| Context property | Implemented | `context: var` or `context: [a, b, c]` |
|
||||
| do: blocks | Implemented | Explicit sequential blocks |
|
||||
| Inline sequence | Implemented | `session "A" -> session "B"` |
|
||||
| Named blocks | Implemented | `block name:` with `do name` invocation |
|
||||
| Parallel blocks | Implemented | `parallel:` for concurrent execution |
|
||||
| Named parallel results | Implemented | `x = session "..."` inside parallel |
|
||||
| Object context | Implemented | `context: { a, b, c }` shorthand |
|
||||
| Join strategies | Implemented | `parallel ("first"):` or `parallel ("any"):` |
|
||||
| Failure policies | Implemented | `parallel (on-fail: "continue"):` |
|
||||
| Repeat blocks | Implemented | `repeat N:` fixed iterations |
|
||||
| Repeat with index | Implemented | `repeat N as i:` with index variable |
|
||||
| For-each blocks | Implemented | `for item in items:` iteration |
|
||||
| For-each with index | Implemented | `for item, i in items:` with index |
|
||||
| Parallel for-each | Implemented | `parallel for item in items:` fan-out |
|
||||
| Unbounded loop | Implemented | `loop:` with optional max iterations |
|
||||
| Loop until | Implemented | `loop until **condition**:` AI-evaluated |
|
||||
| Loop while | Implemented | `loop while **condition**:` AI-evaluated |
|
||||
| Loop with index | Implemented | `loop as i:` or `loop until ... as i:` |
|
||||
| Map pipeline | Implemented | `items \| map:` transform each item |
|
||||
| Filter pipeline | Implemented | `items \| filter:` keep matching items |
|
||||
| Reduce pipeline | Implemented | `items \| reduce(acc, item):` accumulate |
|
||||
| Parallel map | Implemented | `items \| pmap:` concurrent transform |
|
||||
| Pipeline chaining | Implemented | `\| filter: ... \| map: ...` |
|
||||
| Try/catch blocks | Implemented | `try:` with `catch:` for error handling |
|
||||
| Try/catch/finally | Implemented | `finally:` for cleanup |
|
||||
| Error variable | Implemented | `catch as err:` access error context |
|
||||
| Throw statement | Implemented | `throw` or `throw "message"` |
|
||||
| Retry property | Implemented | `retry: 3` automatic retry on failure |
|
||||
| Backoff strategy | Implemented | `backoff: exponential` delay between retries |
|
||||
| Input declarations | Implemented | `input name: "description"` |
|
||||
| Output bindings | Implemented | `output name = expression` |
|
||||
| Program invocation | Implemented | `name(input: value)` call imported programs |
|
||||
| Multi-line strings | Implemented | `"""..."""` preserving whitespace |
|
||||
| String interpolation | Implemented | `"Hello {name}"` variable substitution |
|
||||
| Block parameters | Implemented | `block name(param):` with parameters |
|
||||
| Block invocation args | Implemented | `do name(arg)` passing arguments |
|
||||
| Choice blocks | Implemented | `choice **criteria**: option "label":` |
|
||||
| If/elif/else | Implemented | `if **condition**:` conditional branching |
|
||||
| Persistent agents | Implemented | `persist: true` or `persist: project` |
|
||||
| Resume statement | Implemented | `resume: agent` to continue with memory |
|
||||
| Feature | Status | Description |
|
||||
| ---------------------- | ----------- | -------------------------------------------- |
|
||||
| Comments | Implemented | `# comment` syntax |
|
||||
| Single-line strings | Implemented | `"string"` with escapes |
|
||||
| Simple session | Implemented | `session "prompt"` |
|
||||
| Agent definitions | Implemented | `agent name:` with model/prompt properties |
|
||||
| Session with agent | Implemented | `session: agent` with property overrides |
|
||||
| Use statements | Implemented | `use "@handle/slug" as name` |
|
||||
| Agent skills | Implemented | `skills: ["skill1", "skill2"]` |
|
||||
| Agent permissions | Implemented | `permissions:` block with rules |
|
||||
| Let binding | Implemented | `let name = session "..."` |
|
||||
| Const binding | Implemented | `const name = session "..."` |
|
||||
| Variable reassignment | Implemented | `name = session "..."` (for let only) |
|
||||
| Context property | Implemented | `context: var` or `context: [a, b, c]` |
|
||||
| do: blocks | Implemented | Explicit sequential blocks |
|
||||
| Inline sequence | Implemented | `session "A" -> session "B"` |
|
||||
| Named blocks | Implemented | `block name:` with `do name` invocation |
|
||||
| Parallel blocks | Implemented | `parallel:` for concurrent execution |
|
||||
| Named parallel results | Implemented | `x = session "..."` inside parallel |
|
||||
| Object context | Implemented | `context: { a, b, c }` shorthand |
|
||||
| Join strategies | Implemented | `parallel ("first"):` or `parallel ("any"):` |
|
||||
| Failure policies | Implemented | `parallel (on-fail: "continue"):` |
|
||||
| Repeat blocks | Implemented | `repeat N:` fixed iterations |
|
||||
| Repeat with index | Implemented | `repeat N as i:` with index variable |
|
||||
| For-each blocks | Implemented | `for item in items:` iteration |
|
||||
| For-each with index | Implemented | `for item, i in items:` with index |
|
||||
| Parallel for-each | Implemented | `parallel for item in items:` fan-out |
|
||||
| Unbounded loop | Implemented | `loop:` with optional max iterations |
|
||||
| Loop until | Implemented | `loop until **condition**:` AI-evaluated |
|
||||
| Loop while | Implemented | `loop while **condition**:` AI-evaluated |
|
||||
| Loop with index | Implemented | `loop as i:` or `loop until ... as i:` |
|
||||
| Map pipeline | Implemented | `items \| map:` transform each item |
|
||||
| Filter pipeline | Implemented | `items \| filter:` keep matching items |
|
||||
| Reduce pipeline | Implemented | `items \| reduce(acc, item):` accumulate |
|
||||
| Parallel map | Implemented | `items \| pmap:` concurrent transform |
|
||||
| Pipeline chaining | Implemented | `\| filter: ... \| map: ...` |
|
||||
| Try/catch blocks | Implemented | `try:` with `catch:` for error handling |
|
||||
| Try/catch/finally | Implemented | `finally:` for cleanup |
|
||||
| Error variable | Implemented | `catch as err:` access error context |
|
||||
| Throw statement | Implemented | `throw` or `throw "message"` |
|
||||
| Retry property | Implemented | `retry: 3` automatic retry on failure |
|
||||
| Backoff strategy | Implemented | `backoff: exponential` delay between retries |
|
||||
| Input declarations | Implemented | `input name: "description"` |
|
||||
| Output bindings | Implemented | `output name = expression` |
|
||||
| Program invocation | Implemented | `name(input: value)` call imported programs |
|
||||
| Multi-line strings | Implemented | `"""..."""` preserving whitespace |
|
||||
| String interpolation | Implemented | `"Hello {name}"` variable substitution |
|
||||
| Block parameters | Implemented | `block name(param):` with parameters |
|
||||
| Block invocation args | Implemented | `do name(arg)` passing arguments |
|
||||
| Choice blocks | Implemented | `choice **criteria**: option "label":` |
|
||||
| If/elif/else | Implemented | `if **condition**:` conditional branching |
|
||||
| Persistent agents | Implemented | `persist: true` or `persist: project` |
|
||||
| Resume statement | Implemented | `resume: agent` to continue with memory |
|
||||
|
||||
---
|
||||
|
||||
@@ -351,6 +351,7 @@ use "@handle/slug" as alias
|
||||
### Path Format
|
||||
|
||||
Import paths follow the format `@handle/slug`:
|
||||
|
||||
- `@handle` identifies the program author/organization
|
||||
- `slug` is the program name
|
||||
|
||||
@@ -413,6 +414,7 @@ input depth: "How deep to go (shallow, medium, deep)"
|
||||
### Semantics
|
||||
|
||||
Inputs:
|
||||
|
||||
- Are declared at the top of the program (before executable statements)
|
||||
- Have a name and a description (for documentation)
|
||||
- Become available as variables within the program body
|
||||
@@ -420,11 +422,11 @@ Inputs:
|
||||
|
||||
### Validation Rules
|
||||
|
||||
| Check | Severity | Message |
|
||||
| ---------------------- | -------- | ------------------------------------ |
|
||||
| Empty input name | Error | Input name cannot be empty |
|
||||
| Empty description | Warning | Consider adding a description |
|
||||
| Duplicate input name | Error | Input already declared |
|
||||
| Check | Severity | Message |
|
||||
| ---------------------- | -------- | ---------------------------------------------------- |
|
||||
| Empty input name | Error | Input name cannot be empty |
|
||||
| Empty description | Warning | Consider adding a description |
|
||||
| Duplicate input name | Error | Input already declared |
|
||||
| Input after executable | Error | Inputs must be declared before executable statements |
|
||||
|
||||
---
|
||||
@@ -452,6 +454,7 @@ output sources = session "Extract sources"
|
||||
### Semantics
|
||||
|
||||
The `output` keyword:
|
||||
|
||||
- Marks a variable as an output (visible at assignment, not just at file top)
|
||||
- Works like `let` but also registers the value as a program output
|
||||
- Can appear anywhere in the program body
|
||||
@@ -459,11 +462,11 @@ The `output` keyword:
|
||||
|
||||
### Validation Rules
|
||||
|
||||
| Check | Severity | Message |
|
||||
| ---------------------- | -------- | ------------------------------------ |
|
||||
| Empty output name | Error | Output name cannot be empty |
|
||||
| Duplicate output name | Error | Output already declared |
|
||||
| Output name conflicts | Error | Output name conflicts with variable |
|
||||
| Check | Severity | Message |
|
||||
| --------------------- | -------- | ----------------------------------- |
|
||||
| Empty output name | Error | Output name cannot be empty |
|
||||
| Duplicate output name | Error | Output already declared |
|
||||
| Output name conflicts | Error | Output name conflicts with variable |
|
||||
|
||||
---
|
||||
|
||||
@@ -518,12 +521,12 @@ The imported program runs in its own execution context but shares the same VM se
|
||||
|
||||
### Validation Rules
|
||||
|
||||
| Check | Severity | Message |
|
||||
| ------------------------ | -------- | ------------------------------------ |
|
||||
| Unknown program | Error | Program not imported |
|
||||
| Missing required input | Error | Required input not provided |
|
||||
| Unknown input name | Error | Input not declared in program |
|
||||
| Unknown output property | Error | Output not declared in program |
|
||||
| Check | Severity | Message |
|
||||
| ----------------------- | -------- | ------------------------------ |
|
||||
| Unknown program | Error | Program not imported |
|
||||
| Missing required input | Error | Required input not provided |
|
||||
| Unknown input name | Error | Input not declared in program |
|
||||
| Unknown output property | Error | Output not declared in program |
|
||||
|
||||
---
|
||||
|
||||
@@ -545,13 +548,13 @@ agent name:
|
||||
|
||||
### Properties
|
||||
|
||||
| Property | Type | Values | Description |
|
||||
| ------------- | ---------- | ------------------------------ | ------------------------------------- |
|
||||
| `model` | identifier | `sonnet`, `opus`, `haiku` | The Claude model to use |
|
||||
| `prompt` | string | Any string | System prompt/context for the agent |
|
||||
| `persist` | value | `true`, `project`, or STRING | Enable persistent memory for agent |
|
||||
| `skills` | array | String array | Skills assigned to this agent |
|
||||
| `permissions` | block | Permission rules | Access control for the agent |
|
||||
| Property | Type | Values | Description |
|
||||
| ------------- | ---------- | ---------------------------- | ----------------------------------- |
|
||||
| `model` | identifier | `sonnet`, `opus`, `haiku` | The Claude model to use |
|
||||
| `prompt` | string | Any string | System prompt/context for the agent |
|
||||
| `persist` | value | `true`, `project`, or STRING | Enable persistent memory for agent |
|
||||
| `skills` | array | String array | Skills assigned to this agent |
|
||||
| `permissions` | block | Permission rules | Access control for the agent |
|
||||
|
||||
### Persist Property
|
||||
|
||||
@@ -577,11 +580,11 @@ agent shared:
|
||||
prompt: "Shared across programs"
|
||||
```
|
||||
|
||||
| Value | Memory Location | Lifetime |
|
||||
|-------|-----------------|----------|
|
||||
| `true` | `.prose/runs/{id}/agents/{name}/` | Dies with execution |
|
||||
| `project` | `.prose/agents/{name}/` | Survives executions |
|
||||
| STRING | Specified path | User-controlled |
|
||||
| Value | Memory Location | Lifetime |
|
||||
| --------- | --------------------------------- | ------------------- |
|
||||
| `true` | `.prose/runs/{id}/agents/{name}/` | Dies with execution |
|
||||
| `project` | `.prose/agents/{name}/` | Survives executions |
|
||||
| STRING | Specified path | User-controlled |
|
||||
|
||||
### Skills Property
|
||||
|
||||
@@ -872,10 +875,10 @@ resume: agentName
|
||||
|
||||
### Semantics
|
||||
|
||||
| Keyword | Behavior |
|
||||
|---------|----------|
|
||||
| Keyword | Behavior |
|
||||
| ---------- | ------------------------------------- |
|
||||
| `session:` | Ignores existing memory, starts fresh |
|
||||
| `resume:` | Loads memory, continues with context |
|
||||
| `resume:` | Loads memory, continues with context |
|
||||
|
||||
### Examples
|
||||
|
||||
@@ -902,12 +905,12 @@ let review = resume: captain
|
||||
|
||||
### Validation Rules
|
||||
|
||||
| Check | Severity | Message |
|
||||
|-------|----------|---------|
|
||||
| `resume:` on non-persistent agent | Error | Agent must have `persist:` property to use `resume:` |
|
||||
| `resume:` with no existing memory | Error | No memory file exists for agent; use `session:` for first invocation |
|
||||
| `session:` on persistent agent with memory | Warning | Will ignore existing memory; use `resume:` to continue |
|
||||
| Undefined agent reference | Error | Agent not defined |
|
||||
| Check | Severity | Message |
|
||||
| ------------------------------------------ | -------- | -------------------------------------------------------------------- |
|
||||
| `resume:` on non-persistent agent | Error | Agent must have `persist:` property to use `resume:` |
|
||||
| `resume:` with no existing memory | Error | No memory file exists for agent; use `session:` for first invocation |
|
||||
| `session:` on persistent agent with memory | Warning | Will ignore existing memory; use `resume:` to continue |
|
||||
| Undefined agent reference | Error | Agent not defined |
|
||||
|
||||
---
|
||||
|
||||
@@ -1047,6 +1050,7 @@ for item in items:
|
||||
**Why this constraint:** Since bindings are stored as `bindings/{name}.md`, two variables with the same name would collide on the filesystem. Rather than introduce complex scoping rules, we enforce uniqueness.
|
||||
|
||||
**Collision scenarios this prevents:**
|
||||
|
||||
1. Variable inside loop shadows variable outside loop
|
||||
2. Variables in different `if`/`elif`/`else` branches with same name
|
||||
3. Block parameters shadowing outer variables
|
||||
@@ -2643,51 +2647,51 @@ The validator checks programs for errors and warnings before execution.
|
||||
|
||||
### Errors (Block Execution)
|
||||
|
||||
| Code | Description |
|
||||
| ---- | ----------------------------------- |
|
||||
| E001 | Unterminated string literal |
|
||||
| E002 | Unknown escape sequence in string |
|
||||
| E003 | Session missing prompt or agent |
|
||||
| E004 | Unexpected token |
|
||||
| E005 | Invalid syntax |
|
||||
| E006 | Duplicate agent definition |
|
||||
| E007 | Undefined agent reference |
|
||||
| E008 | Invalid model value |
|
||||
| E009 | Duplicate property |
|
||||
| E010 | Duplicate use statement |
|
||||
| E011 | Empty use path |
|
||||
| E012 | Invalid use path format |
|
||||
| E013 | Skills must be an array |
|
||||
| E014 | Skill name must be a string |
|
||||
| E015 | Permissions must be a block |
|
||||
| E016 | Permission pattern must be a string |
|
||||
| E017 | `resume:` requires persistent agent |
|
||||
| E018 | `resume:` with no existing memory |
|
||||
| Code | Description |
|
||||
| ---- | ---------------------------------------- |
|
||||
| E001 | Unterminated string literal |
|
||||
| E002 | Unknown escape sequence in string |
|
||||
| E003 | Session missing prompt or agent |
|
||||
| E004 | Unexpected token |
|
||||
| E005 | Invalid syntax |
|
||||
| E006 | Duplicate agent definition |
|
||||
| E007 | Undefined agent reference |
|
||||
| E008 | Invalid model value |
|
||||
| E009 | Duplicate property |
|
||||
| E010 | Duplicate use statement |
|
||||
| E011 | Empty use path |
|
||||
| E012 | Invalid use path format |
|
||||
| E013 | Skills must be an array |
|
||||
| E014 | Skill name must be a string |
|
||||
| E015 | Permissions must be a block |
|
||||
| E016 | Permission pattern must be a string |
|
||||
| E017 | `resume:` requires persistent agent |
|
||||
| E018 | `resume:` with no existing memory |
|
||||
| E019 | Duplicate variable name (flat namespace) |
|
||||
| E020 | Empty input name |
|
||||
| E021 | Duplicate input declaration |
|
||||
| E022 | Input after executable statement |
|
||||
| E023 | Empty output name |
|
||||
| E024 | Duplicate output declaration |
|
||||
| E025 | Unknown program in invocation |
|
||||
| E026 | Missing required input |
|
||||
| E027 | Unknown input name in invocation |
|
||||
| E028 | Unknown output property access |
|
||||
| E020 | Empty input name |
|
||||
| E021 | Duplicate input declaration |
|
||||
| E022 | Input after executable statement |
|
||||
| E023 | Empty output name |
|
||||
| E024 | Duplicate output declaration |
|
||||
| E025 | Unknown program in invocation |
|
||||
| E026 | Missing required input |
|
||||
| E027 | Unknown input name in invocation |
|
||||
| E028 | Unknown output property access |
|
||||
|
||||
### Warnings (Non-blocking)
|
||||
|
||||
| Code | Description |
|
||||
| ---- | ---------------------------------------- |
|
||||
| W001 | Empty session prompt |
|
||||
| W002 | Whitespace-only session prompt |
|
||||
| W003 | Session prompt exceeds 10,000 characters |
|
||||
| W004 | Empty prompt property |
|
||||
| W005 | Unknown property name |
|
||||
| W006 | Unknown import source format |
|
||||
| W007 | Skill not imported |
|
||||
| W008 | Unknown permission type |
|
||||
| W009 | Unknown permission value |
|
||||
| W010 | Empty skills array |
|
||||
| Code | Description |
|
||||
| ---- | --------------------------------------------------- |
|
||||
| W001 | Empty session prompt |
|
||||
| W002 | Whitespace-only session prompt |
|
||||
| W003 | Session prompt exceeds 10,000 characters |
|
||||
| W004 | Empty prompt property |
|
||||
| W005 | Unknown property name |
|
||||
| W006 | Unknown import source format |
|
||||
| W007 | Skill not imported |
|
||||
| W008 | Unknown permission type |
|
||||
| W009 | Unknown permission value |
|
||||
| W010 | Empty skills array |
|
||||
| W011 | `session:` on persistent agent with existing memory |
|
||||
|
||||
### Error Message Format
|
||||
|
||||
@@ -108,13 +108,13 @@ These examples demonstrate workflows using OpenProse's full feature set.
|
||||
|
||||
### Meta / Self-Hosting (44-48)
|
||||
|
||||
| File | Description |
|
||||
| --------------------------------- | ------------------------------------------------------ |
|
||||
| `44-run-endpoint-ux-test.prose` | Concurrent agents testing the /run API endpoint |
|
||||
| `45-plugin-release.prose` | OpenProse plugin release workflow (this repo) |
|
||||
| `46-workflow-crystallizer.prose` | Reflective: observes thread, extracts workflow, writes .prose |
|
||||
| File | Description |
|
||||
| ------------------------------------ | ------------------------------------------------------------------ |
|
||||
| `44-run-endpoint-ux-test.prose` | Concurrent agents testing the /run API endpoint |
|
||||
| `45-plugin-release.prose` | OpenProse plugin release workflow (this repo) |
|
||||
| `46-workflow-crystallizer.prose` | Reflective: observes thread, extracts workflow, writes .prose |
|
||||
| `47-language-self-improvement.prose` | Meta-level 2: analyzes .prose corpus to evolve the language itself |
|
||||
| `48-habit-miner.prose` | Mines AI session logs for patterns, generates .prose automations |
|
||||
| `48-habit-miner.prose` | Mines AI session logs for patterns, generates .prose automations |
|
||||
|
||||
## The Architect By Simulation Pattern
|
||||
|
||||
|
||||
@@ -6,14 +6,14 @@ They are included to show the direction of the language and gather feedback on t
|
||||
|
||||
## Planned Features
|
||||
|
||||
| Feature | Status | Example File |
|
||||
|---------|--------|--------------|
|
||||
| Agent definitions | Planned | `simple-pipeline.prose` |
|
||||
| Named sessions | Planned | `simple-pipeline.prose` |
|
||||
| Parallel execution | Planned | `parallel-review.prose` |
|
||||
| Variables & context | Planned | `iterative-refinement.prose` |
|
||||
| Loops & conditionals | Planned | `iterative-refinement.prose` |
|
||||
| Imports | Planned | `syntax/open-prose-syntax.prose` |
|
||||
| Feature | Status | Example File |
|
||||
| -------------------- | ------- | -------------------------------- |
|
||||
| Agent definitions | Planned | `simple-pipeline.prose` |
|
||||
| Named sessions | Planned | `simple-pipeline.prose` |
|
||||
| Parallel execution | Planned | `parallel-review.prose` |
|
||||
| Variables & context | Planned | `iterative-refinement.prose` |
|
||||
| Loops & conditionals | Planned | `iterative-refinement.prose` |
|
||||
| Imports | Planned | `syntax/open-prose-syntax.prose` |
|
||||
|
||||
## Do Not Run These Examples
|
||||
|
||||
|
||||
@@ -200,26 +200,26 @@ session "Execute main workflow"
|
||||
|
||||
Match model capability to task complexity:
|
||||
|
||||
| Model | Best For | Examples |
|
||||
|-------|----------|----------|
|
||||
| **Sonnet 4.5** | Orchestration, control flow, coordination | VM execution, captain's chair, workflow routing |
|
||||
| **Opus 4.5** | Hard/difficult work requiring deep reasoning | Complex analysis, strategic decisions, novel problem-solving |
|
||||
| **Haiku** | Simple, self-evident tasks (use sparingly) | Classification, summarization, formatting |
|
||||
| Model | Best For | Examples |
|
||||
| -------------- | -------------------------------------------- | ------------------------------------------------------------ |
|
||||
| **Sonnet 4.5** | Orchestration, control flow, coordination | VM execution, captain's chair, workflow routing |
|
||||
| **Opus 4.5** | Hard/difficult work requiring deep reasoning | Complex analysis, strategic decisions, novel problem-solving |
|
||||
| **Haiku** | Simple, self-evident tasks (use sparingly) | Classification, summarization, formatting |
|
||||
|
||||
**Key insight:** Sonnet 4.5 excels at *orchestrating* agents and managing control flow—it's the ideal model for the OpenProse VM itself and for "captain" agents that coordinate work. Opus 4.5 should be reserved for agents doing genuinely difficult intellectual work. Haiku can handle simple tasks but should generally be avoided where quality matters.
|
||||
**Key insight:** Sonnet 4.5 excels at _orchestrating_ agents and managing control flow—it's the ideal model for the OpenProse VM itself and for "captain" agents that coordinate work. Opus 4.5 should be reserved for agents doing genuinely difficult intellectual work. Haiku can handle simple tasks but should generally be avoided where quality matters.
|
||||
|
||||
**Detailed task-to-model mapping:**
|
||||
|
||||
| Task Type | Model | Rationale |
|
||||
|-----------|-------|-----------|
|
||||
| Orchestration, routing, coordination | Sonnet | Fast, good at following structure |
|
||||
| Investigation, debugging, diagnosis | Sonnet | Structured analysis, checklist-style work |
|
||||
| Triage, classification, categorization | Sonnet | Clear criteria, deterministic decisions |
|
||||
| Code review, verification (checklist) | Sonnet | Following defined review criteria |
|
||||
| Simple implementation, fixes | Sonnet | Applying known patterns |
|
||||
| Complex multi-file synthesis | Opus | Needs to hold many things in context |
|
||||
| Novel architecture, strategic planning | Opus | Requires creative problem-solving |
|
||||
| Ambiguous problems, unclear requirements | Opus | Needs to reason through uncertainty |
|
||||
| Task Type | Model | Rationale |
|
||||
| ---------------------------------------- | ------ | ----------------------------------------- |
|
||||
| Orchestration, routing, coordination | Sonnet | Fast, good at following structure |
|
||||
| Investigation, debugging, diagnosis | Sonnet | Structured analysis, checklist-style work |
|
||||
| Triage, classification, categorization | Sonnet | Clear criteria, deterministic decisions |
|
||||
| Code review, verification (checklist) | Sonnet | Following defined review criteria |
|
||||
| Simple implementation, fixes | Sonnet | Applying known patterns |
|
||||
| Complex multi-file synthesis | Opus | Needs to hold many things in context |
|
||||
| Novel architecture, strategic planning | Opus | Requires creative problem-solving |
|
||||
| Ambiguous problems, unclear requirements | Opus | Needs to reason through uncertainty |
|
||||
|
||||
**Rule of thumb:** If you can write a checklist for the task, Sonnet can do it. If the task requires genuine creativity or navigating ambiguity, use Opus.
|
||||
|
||||
|
||||
@@ -33,30 +33,30 @@ Options:
|
||||
- **Learn the syntax**: Show examples from `examples/`, explain the VM model
|
||||
- **Explore possibilities**: Walk through key examples like `37-the-forge.prose` or `28-gas-town.prose`
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Available Commands
|
||||
|
||||
| Command | What it does |
|
||||
|---------|--------------|
|
||||
| `prose help` | This help - guides you to what you need |
|
||||
| `prose run <file>` | Execute a .prose program |
|
||||
| `prose compile <file>` | Validate syntax without running |
|
||||
| `prose update` | Migrate legacy workspace files |
|
||||
| `prose examples` | Browse and run example programs |
|
||||
| Command | What it does |
|
||||
| ---------------------- | --------------------------------------- |
|
||||
| `prose help` | This help - guides you to what you need |
|
||||
| `prose run <file>` | Execute a .prose program |
|
||||
| `prose compile <file>` | Validate syntax without running |
|
||||
| `prose update` | Migrate legacy workspace files |
|
||||
| `prose examples` | Browse and run example programs |
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
**Run an example:**
|
||||
|
||||
```
|
||||
prose run examples/01-hello-world.prose
|
||||
```
|
||||
|
||||
**Create your first program:**
|
||||
|
||||
```
|
||||
prose help
|
||||
→ Select "Build something new"
|
||||
@@ -123,21 +123,22 @@ For complete syntax and validation rules, see `compiler.md`.
|
||||
|
||||
The `examples/` directory contains 37 example programs:
|
||||
|
||||
| Range | Category |
|
||||
|-------|----------|
|
||||
| 01-08 | Basics (hello world, research, code review, debugging) |
|
||||
| 09-12 | Agents and skills |
|
||||
| 13-15 | Variables and composition |
|
||||
| 16-19 | Parallel execution |
|
||||
| 20-21 | Loops and pipelines |
|
||||
| 22-23 | Error handling |
|
||||
| 24-27 | Advanced (choice, conditionals, blocks, interpolation) |
|
||||
| 28 | Gas Town (multi-agent orchestration) |
|
||||
| 29-31 | Captain's chair pattern (persistent orchestrator) |
|
||||
| Range | Category |
|
||||
| ----- | --------------------------------------------------------------------------------- |
|
||||
| 01-08 | Basics (hello world, research, code review, debugging) |
|
||||
| 09-12 | Agents and skills |
|
||||
| 13-15 | Variables and composition |
|
||||
| 16-19 | Parallel execution |
|
||||
| 20-21 | Loops and pipelines |
|
||||
| 22-23 | Error handling |
|
||||
| 24-27 | Advanced (choice, conditionals, blocks, interpolation) |
|
||||
| 28 | Gas Town (multi-agent orchestration) |
|
||||
| 29-31 | Captain's chair pattern (persistent orchestrator) |
|
||||
| 33-36 | Production workflows (PR auto-fix, content pipeline, feature factory, bug hunter) |
|
||||
| 37 | The Forge (build a browser from scratch) |
|
||||
| 37 | The Forge (build a browser from scratch) |
|
||||
|
||||
**Recommended starting points:**
|
||||
|
||||
- `01-hello-world.prose` - Simplest possible program
|
||||
- `16-parallel-reviews.prose` - See parallel execution
|
||||
- `37-the-forge.prose` - Watch AI build a web browser
|
||||
|
||||
@@ -6,21 +6,21 @@ Core programs that ship with OpenProse. Production-quality, well-tested programs
|
||||
|
||||
### Evaluation & Improvement
|
||||
|
||||
| Program | Description |
|
||||
|---------|-------------|
|
||||
| `inspector.prose` | Post-run analysis for runtime fidelity and task effectiveness |
|
||||
| `vm-improver.prose` | Analyzes inspections and proposes PRs to improve the VM |
|
||||
| Program | Description |
|
||||
| ------------------------ | -------------------------------------------------------------- |
|
||||
| `inspector.prose` | Post-run analysis for runtime fidelity and task effectiveness |
|
||||
| `vm-improver.prose` | Analyzes inspections and proposes PRs to improve the VM |
|
||||
| `program-improver.prose` | Analyzes inspections and proposes PRs to improve .prose source |
|
||||
| `cost-analyzer.prose` | Token usage and cost pattern analysis |
|
||||
| `calibrator.prose` | Validates light evaluations against deep evaluations |
|
||||
| `error-forensics.prose` | Root cause analysis for failed runs |
|
||||
| `cost-analyzer.prose` | Token usage and cost pattern analysis |
|
||||
| `calibrator.prose` | Validates light evaluations against deep evaluations |
|
||||
| `error-forensics.prose` | Root cause analysis for failed runs |
|
||||
|
||||
### Memory
|
||||
|
||||
| Program | Description |
|
||||
|---------|-------------|
|
||||
| `user-memory.prose` | Cross-project persistent personal memory |
|
||||
| `project-memory.prose` | Project-scoped institutional memory |
|
||||
| Program | Description |
|
||||
| ---------------------- | ---------------------------------------- |
|
||||
| `user-memory.prose` | Cross-project persistent personal memory |
|
||||
| `project-memory.prose` | Project-scoped institutional memory |
|
||||
|
||||
## The Improvement Loop
|
||||
|
||||
@@ -40,6 +40,7 @@ The evaluation programs form a recursive improvement cycle:
|
||||
```
|
||||
|
||||
Supporting analysis:
|
||||
|
||||
- **cost-analyzer** — Where does the money go? Optimization opportunities.
|
||||
- **calibrator** — Are cheap evaluations reliable proxies for expensive ones?
|
||||
- **error-forensics** — Why did a run fail? Root cause analysis.
|
||||
@@ -84,11 +85,13 @@ prose run lib/project-memory.prose --backend sqlite+
|
||||
The memory programs use persistent agents to accumulate knowledge:
|
||||
|
||||
**user-memory** (`persist: user`)
|
||||
|
||||
- Learns your preferences, decisions, patterns across all projects
|
||||
- Remembers mistakes and lessons learned
|
||||
- Answers questions from accumulated knowledge
|
||||
|
||||
**project-memory** (`persist: project`)
|
||||
|
||||
- Understands this project's architecture and decisions
|
||||
- Tracks why things are the way they are
|
||||
- Answers questions with project-specific context
|
||||
|
||||
@@ -98,12 +98,12 @@ Execution scope:
|
||||
|
||||
**What this tells you:**
|
||||
|
||||
| Field | Meaning |
|
||||
|-------|---------|
|
||||
| `execution_id` | Unique ID for this specific block invocation |
|
||||
| `block` | Name of the block you're executing within |
|
||||
| `depth` | How deep in the call stack (1 = first level) |
|
||||
| `parent_execution_id` | The invoking frame's ID (for scope chain) |
|
||||
| Field | Meaning |
|
||||
| --------------------- | -------------------------------------------- |
|
||||
| `execution_id` | Unique ID for this specific block invocation |
|
||||
| `block` | Name of the block you're executing within |
|
||||
| `depth` | How deep in the call stack (1 = first level) |
|
||||
| `parent_execution_id` | The invoking frame's ID (for scope chain) |
|
||||
|
||||
**How to use it:**
|
||||
|
||||
@@ -125,10 +125,10 @@ If you're a persistent agent, you maintain state across sessions via a memory fi
|
||||
|
||||
Persistent agents have **two separate outputs** that must not be confused:
|
||||
|
||||
| Output | What It Is | Where It Goes | Purpose |
|
||||
|--------|------------|---------------|---------|
|
||||
| **Binding** | The result of THIS task | `bindings/{name}.md` or database | Passed to other sessions via `context:` |
|
||||
| **Memory** | Your accumulated knowledge | `agents/{name}/memory.md` or database | Carried forward to YOUR future invocations |
|
||||
| Output | What It Is | Where It Goes | Purpose |
|
||||
| ----------- | -------------------------- | ------------------------------------- | ------------------------------------------ |
|
||||
| **Binding** | The result of THIS task | `bindings/{name}.md` or database | Passed to other sessions via `context:` |
|
||||
| **Memory** | Your accumulated knowledge | `agents/{name}/memory.md` or database | Carried forward to YOUR future invocations |
|
||||
|
||||
**The binding is task-specific.** If you're asked to "review the plan," the binding contains your review.
|
||||
|
||||
@@ -358,7 +358,7 @@ For regular sessions with output capture (`let x = session "..."`), write to the
|
||||
# {name}
|
||||
|
||||
kind: {let|const|output|input}
|
||||
execution_id: {id} # Include if inside a block invocation (omit for root scope)
|
||||
execution_id: {id} # Include if inside a block invocation (omit for root scope)
|
||||
|
||||
source:
|
||||
|
||||
@@ -498,6 +498,7 @@ Summary: {1-2 sentence summary of what's in the binding}
|
||||
```
|
||||
|
||||
**Example (filesystem state, root scope):**
|
||||
|
||||
```
|
||||
Binding written: research
|
||||
Location: .prose/runs/20260116-143052-a7b3c9/bindings/research.md
|
||||
@@ -505,6 +506,7 @@ Summary: Comprehensive AI safety research covering alignment, robustness, and in
|
||||
```
|
||||
|
||||
**Example (filesystem state, inside block invocation):**
|
||||
|
||||
```
|
||||
Binding written: result
|
||||
Location: .prose/runs/20260116-143052-a7b3c9/bindings/result__43.md
|
||||
@@ -513,6 +515,7 @@ Summary: Processed chunk into 3 sub-parts for recursive processing.
|
||||
```
|
||||
|
||||
**Example (PostgreSQL state):**
|
||||
|
||||
```
|
||||
Binding written: research
|
||||
Location: openprose.bindings WHERE name='research' AND run_id='20260116-143052-a7b3c9'
|
||||
@@ -520,6 +523,7 @@ Summary: Comprehensive AI safety research covering alignment, robustness, and in
|
||||
```
|
||||
|
||||
**Example (PostgreSQL state, inside block invocation):**
|
||||
|
||||
```
|
||||
Binding written: result
|
||||
Location: openprose.bindings WHERE name='result' AND run_id='20260116-143052-a7b3c9' AND execution_id=43
|
||||
@@ -541,6 +545,7 @@ The VM never holds full binding values in its working memory. This is intentiona
|
||||
Do NOT return your full output in the Task tool response. The VM will ignore it.
|
||||
|
||||
**Bad:**
|
||||
|
||||
```
|
||||
Here's my research:
|
||||
|
||||
@@ -549,6 +554,7 @@ AI safety is a field that studies how to create artificial intelligence systems
|
||||
```
|
||||
|
||||
**Good:**
|
||||
|
||||
```
|
||||
Binding written: research
|
||||
Location: .prose/runs/20260116-143052-a7b3c9/bindings/research.md
|
||||
|
||||
@@ -28,14 +28,14 @@ This document defines how to execute OpenProse programs. You are the OpenProse V
|
||||
|
||||
OpenProse is invoked via `prose` commands:
|
||||
|
||||
| Command | Action |
|
||||
|---------|--------|
|
||||
| `prose run <file.prose>` | Execute a local `.prose` program |
|
||||
| `prose run handle/slug` | Fetch from registry and execute |
|
||||
| `prose compile <file>` | Validate syntax without executing |
|
||||
| `prose help` | Show help and examples |
|
||||
| `prose examples` | List or run bundled examples |
|
||||
| `prose update` | Migrate legacy workspace files |
|
||||
| Command | Action |
|
||||
| ------------------------ | --------------------------------- |
|
||||
| `prose run <file.prose>` | Execute a local `.prose` program |
|
||||
| `prose run handle/slug` | Fetch from registry and execute |
|
||||
| `prose compile <file>` | Validate syntax without executing |
|
||||
| `prose help` | Show help and examples |
|
||||
| `prose examples` | List or run bundled examples |
|
||||
| `prose update` | Migrate legacy workspace files |
|
||||
|
||||
### Remote Programs
|
||||
|
||||
@@ -51,11 +51,13 @@ prose run alice/code-review # Fetches https://p.prose.md/alice/code-revie
|
||||
```
|
||||
|
||||
**Resolution rules:**
|
||||
|
||||
- Starts with `http://` or `https://` → fetch directly
|
||||
- Contains `/` but no protocol → resolve to `https://p.prose.md/{path}`
|
||||
- Otherwise → treat as local file path
|
||||
|
||||
This same resolution applies to `use` statements inside programs:
|
||||
|
||||
```prose
|
||||
use "https://example.com/my-program.prose" # Direct URL
|
||||
use "alice/research" as research # Registry shorthand
|
||||
@@ -111,18 +113,18 @@ When you execute a `.prose` program, you ARE the virtual machine. This is not a
|
||||
|
||||
Traditional dependency injection containers wire up components from configuration. You do the same—but with understanding:
|
||||
|
||||
| Declared Primitive | Your Responsibility |
|
||||
| ---------------------------- | ---------------------------------------------------------- |
|
||||
| Declared Primitive | Your Responsibility |
|
||||
| --------------------------- | ---------------------------------------------------------- |
|
||||
| `use "handle/slug" as name` | Fetch program from p.prose.md, register in Import Registry |
|
||||
| `input topic: "..."` | Bind value from caller, make available as variable |
|
||||
| `output findings = ...` | Mark value as output, return to caller on completion |
|
||||
| `agent researcher:` | Register this agent template for later use |
|
||||
| `session: researcher` | Resolve the agent, merge properties, spawn the session |
|
||||
| `resume: captain` | Load agent memory, spawn session with memory context |
|
||||
| `context: { a, b }` | Wire the outputs of `a` and `b` into this session's input |
|
||||
| `parallel:` branches | Coordinate concurrent execution, collect results |
|
||||
| `block review(topic):` | Store this reusable component, invoke when called |
|
||||
| `name(input: value)` | Invoke imported program with inputs, receive outputs |
|
||||
| `input topic: "..."` | Bind value from caller, make available as variable |
|
||||
| `output findings = ...` | Mark value as output, return to caller on completion |
|
||||
| `agent researcher:` | Register this agent template for later use |
|
||||
| `session: researcher` | Resolve the agent, merge properties, spawn the session |
|
||||
| `resume: captain` | Load agent memory, spawn session with memory context |
|
||||
| `context: { a, b }` | Wire the outputs of `a` and `b` into this session's input |
|
||||
| `parallel:` branches | Coordinate concurrent execution, collect results |
|
||||
| `block review(topic):` | Store this reusable component, invoke when called |
|
||||
| `name(input: value)` | Invoke imported program with inputs, receive outputs |
|
||||
|
||||
You are the container that holds these declarations and wires them together at runtime. The program declares _what_; you determine _how_ to connect them.
|
||||
|
||||
|
||||
@@ -104,12 +104,13 @@ The execution state file shows the program's current position using **annotated
|
||||
**Only the VM writes this file.** Subagents never modify `state.md`.
|
||||
|
||||
The format shows:
|
||||
|
||||
- **Full history** of executed code with inline annotations
|
||||
- **Current position** clearly marked with status
|
||||
- **~5-10 lines ahead** of current position (what's coming next)
|
||||
- **Index** of all bindings and agents with file paths
|
||||
|
||||
```markdown
|
||||
````markdown
|
||||
# Execution State
|
||||
|
||||
run: 20260115-143052-a7b3c9
|
||||
@@ -144,6 +145,7 @@ resume: captain # [...next...]
|
||||
prompt: "Review the synthesis"
|
||||
context: synthesis
|
||||
```
|
||||
````
|
||||
|
||||
## Active Constructs
|
||||
|
||||
@@ -162,26 +164,27 @@ resume: captain # [...next...]
|
||||
|
||||
### Bindings
|
||||
|
||||
| Name | Kind | Path | Execution ID |
|
||||
|------|------|------|--------------|
|
||||
| research | let | bindings/research.md | (root) |
|
||||
| a | let | bindings/a.md | (root) |
|
||||
| result | let | bindings/result__43.md | 43 |
|
||||
| Name | Kind | Path | Execution ID |
|
||||
| -------- | ---- | ------------------------ | ------------ |
|
||||
| research | let | bindings/research.md | (root) |
|
||||
| a | let | bindings/a.md | (root) |
|
||||
| result | let | bindings/result\_\_43.md | 43 |
|
||||
|
||||
### Agents
|
||||
|
||||
| Name | Scope | Path |
|
||||
|------|-------|------|
|
||||
| Name | Scope | Path |
|
||||
| ------- | --------- | --------------- |
|
||||
| captain | execution | agents/captain/ |
|
||||
|
||||
## Call Stack
|
||||
|
||||
| execution_id | block | depth | status |
|
||||
|--------------|-------|-------|--------|
|
||||
| 43 | process | 3 | executing |
|
||||
| 42 | process | 2 | waiting |
|
||||
| 41 | process | 1 | waiting |
|
||||
```
|
||||
| execution_id | block | depth | status |
|
||||
| ------------ | ------- | ----- | --------- |
|
||||
| 43 | process | 3 | executing |
|
||||
| 42 | process | 2 | waiting |
|
||||
| 41 | process | 1 | waiting |
|
||||
|
||||
````
|
||||
|
||||
**Status annotations:**
|
||||
|
||||
@@ -209,14 +212,15 @@ source:
|
||||
```prose
|
||||
let research = session: researcher
|
||||
prompt: "Research AI safety"
|
||||
```
|
||||
````
|
||||
|
||||
---
|
||||
|
||||
AI safety research covers several key areas including alignment,
|
||||
robustness, and interpretability. The field has grown significantly
|
||||
since 2020 with major contributions from...
|
||||
```
|
||||
|
||||
````
|
||||
|
||||
**Structure:**
|
||||
- Header with binding name
|
||||
@@ -240,7 +244,7 @@ Sessions without explicit output capture still produce results:
|
||||
|
||||
```prose
|
||||
session "Analyze the codebase" # No `let x = ...` capture
|
||||
```
|
||||
````
|
||||
|
||||
These get auto-generated names with an `anon_` prefix:
|
||||
|
||||
@@ -259,25 +263,29 @@ When a binding is created inside a block invocation, it's scoped to that executi
|
||||
**Naming convention:** `{name}__{execution_id}.md`
|
||||
|
||||
Examples:
|
||||
|
||||
- `bindings/result__43.md` — binding `result` in execution_id 43
|
||||
- `bindings/parts__44.md` — binding `parts` in execution_id 44
|
||||
|
||||
**File format with execution scope:**
|
||||
|
||||
```markdown
|
||||
````markdown
|
||||
# result
|
||||
|
||||
kind: let
|
||||
execution_id: 43
|
||||
|
||||
source:
|
||||
|
||||
```prose
|
||||
let result = session "Process chunk"
|
||||
```
|
||||
````
|
||||
|
||||
---
|
||||
|
||||
Processed chunk into 3 sub-parts...
|
||||
|
||||
```
|
||||
|
||||
**Scope resolution:** The VM resolves variable references by checking:
|
||||
@@ -291,15 +299,17 @@ The first match wins.
|
||||
**Example directory for recursive calls:**
|
||||
|
||||
```
|
||||
|
||||
bindings/
|
||||
├── data.md # Root scope input
|
||||
├── result__1.md # First process() invocation
|
||||
├── parts__1.md # Parts from first invocation
|
||||
├── result__2.md # Recursive call (depth 2)
|
||||
├── parts__2.md # Parts from depth 2
|
||||
├── result__3.md # Recursive call (depth 3)
|
||||
├── data.md # Root scope input
|
||||
├── result**1.md # First process() invocation
|
||||
├── parts**1.md # Parts from first invocation
|
||||
├── result**2.md # Recursive call (depth 2)
|
||||
├── parts**2.md # Parts from depth 2
|
||||
├── result\_\_3.md # Recursive call (depth 3)
|
||||
└── ...
|
||||
```
|
||||
|
||||
````
|
||||
|
||||
---
|
||||
|
||||
@@ -326,7 +336,7 @@ Architecture uses Express + PostgreSQL. Test coverage target is 80%.
|
||||
|
||||
- Rate limiting not yet implemented on login endpoint
|
||||
- Need to verify OAuth flow works with new token format
|
||||
```
|
||||
````
|
||||
|
||||
#### `agents/{name}/{name}-NNN.md` (Segments)
|
||||
|
||||
@@ -350,11 +360,11 @@ prompt: "Review the research findings"
|
||||
|
||||
## Who Writes What
|
||||
|
||||
| File | Written By |
|
||||
|------|------------|
|
||||
| `state.md` | VM only |
|
||||
| `bindings/{name}.md` | Subagent |
|
||||
| `agents/{name}/memory.md` | Persistent agent |
|
||||
| File | Written By |
|
||||
| ----------------------------- | ---------------- |
|
||||
| `state.md` | VM only |
|
||||
| `bindings/{name}.md` | Subagent |
|
||||
| `agents/{name}/memory.md` | Persistent agent |
|
||||
| `agents/{name}/{name}-NNN.md` | Persistent agent |
|
||||
|
||||
The VM orchestrates; subagents write their own outputs directly to the filesystem. **The VM never holds full binding values—it tracks file paths.**
|
||||
@@ -367,7 +377,7 @@ When the VM spawns a session, it tells the subagent where to write output.
|
||||
|
||||
### For Regular Sessions
|
||||
|
||||
```
|
||||
````
|
||||
When you complete this task, write your output to:
|
||||
.prose/runs/20260115-143052-a7b3c9/bindings/research.md
|
||||
|
||||
@@ -380,24 +390,27 @@ source:
|
||||
```prose
|
||||
let research = session: researcher
|
||||
prompt: "Research AI safety"
|
||||
```
|
||||
````
|
||||
|
||||
---
|
||||
|
||||
[Your output here]
|
||||
|
||||
```
|
||||
|
||||
### For Persistent Agents (resume:)
|
||||
|
||||
```
|
||||
|
||||
Your memory is at:
|
||||
.prose/runs/20260115-143052-a7b3c9/agents/captain/memory.md
|
||||
.prose/runs/20260115-143052-a7b3c9/agents/captain/memory.md
|
||||
|
||||
Read it first to understand your prior context. When done, update it
|
||||
with your compacted state following the guidelines in primitives/session.md.
|
||||
|
||||
Also write your segment record to:
|
||||
.prose/runs/20260115-143052-a7b3c9/agents/captain/captain-003.md
|
||||
.prose/runs/20260115-143052-a7b3c9/agents/captain/captain-003.md
|
||||
|
||||
```
|
||||
|
||||
### What Subagents Return to the VM
|
||||
@@ -406,17 +419,21 @@ After writing output, the subagent returns a **confirmation message**—not the
|
||||
|
||||
**Root scope (outside block invocations):**
|
||||
```
|
||||
|
||||
Binding written: research
|
||||
Location: .prose/runs/20260115-143052-a7b3c9/bindings/research.md
|
||||
Summary: AI safety research covering alignment, robustness, and interpretability with 15 citations.
|
||||
|
||||
```
|
||||
|
||||
**Inside block invocation (include execution_id):**
|
||||
```
|
||||
|
||||
Binding written: result
|
||||
Location: .prose/runs/20260115-143052-a7b3c9/bindings/result__43.md
|
||||
Location: .prose/runs/20260115-143052-a7b3c9/bindings/result\_\_43.md
|
||||
Execution ID: 43
|
||||
Summary: Processed chunk into 3 sub-parts for recursive processing.
|
||||
|
||||
```
|
||||
|
||||
The VM records the location and continues. It does NOT read the file—it passes the reference to subsequent sessions that need the context.
|
||||
@@ -428,16 +445,18 @@ The VM records the location and continues. It does NOT read the file—it passes
|
||||
Imported programs use the **same unified structure recursively**:
|
||||
|
||||
```
|
||||
|
||||
.prose/runs/{id}/imports/{handle}--{slug}/
|
||||
├── program.prose
|
||||
├── state.md
|
||||
├── bindings/
|
||||
│ └── {name}.md
|
||||
├── imports/ # Nested imports go here
|
||||
│ └── {handle2}--{slug2}/
|
||||
│ └── ...
|
||||
│ └── {name}.md
|
||||
├── imports/ # Nested imports go here
|
||||
│ └── {handle2}--{slug2}/
|
||||
│ └── ...
|
||||
└── agents/
|
||||
└── {name}/
|
||||
└── {name}/
|
||||
|
||||
```
|
||||
|
||||
This allows unlimited nesting depth while maintaining consistent structure at every level.
|
||||
@@ -476,3 +495,4 @@ If execution is interrupted, resume by:
|
||||
3. Continuing from the marked position
|
||||
|
||||
The `state.md` file contains everything needed to understand where execution stopped and what has been accomplished.
|
||||
```
|
||||
|
||||
@@ -28,13 +28,13 @@ In-context state uses text-prefixed markers to persist state within the conversa
|
||||
|
||||
In-context state is appropriate for:
|
||||
|
||||
| Factor | In-Context | Use File-Based Instead |
|
||||
|--------|------------|------------------------|
|
||||
| Statement count | < 30 statements | >= 30 statements |
|
||||
| Parallel branches | < 5 concurrent | >= 5 concurrent |
|
||||
| Imported programs | 0-2 imports | >= 3 imports |
|
||||
| Nested depth | <= 2 levels | > 2 levels |
|
||||
| Expected duration | < 5 minutes | >= 5 minutes |
|
||||
| Factor | In-Context | Use File-Based Instead |
|
||||
| ----------------- | --------------- | ---------------------- |
|
||||
| Statement count | < 30 statements | >= 30 statements |
|
||||
| Parallel branches | < 5 concurrent | >= 5 concurrent |
|
||||
| Imported programs | 0-2 imports | >= 3 imports |
|
||||
| Nested depth | <= 2 levels | > 2 levels |
|
||||
| Expected duration | < 5 minutes | >= 5 minutes |
|
||||
|
||||
Announce your state mode at program start:
|
||||
|
||||
@@ -49,23 +49,23 @@ OpenProse Program Start
|
||||
|
||||
Use text-prefixed markers for each state change:
|
||||
|
||||
| Marker | Category | Usage |
|
||||
|--------|----------|-------|
|
||||
| [Program] | Program | Start, end, definition collection |
|
||||
| [Position] | Position | Current statement being executed |
|
||||
| [Binding] | Binding | Variable assignment or update |
|
||||
| [Input] | Input | Receiving inputs from caller |
|
||||
| [Output] | Output | Producing outputs for caller |
|
||||
| [Import] | Import | Fetching and invoking imported programs |
|
||||
| [Success] | Success | Session or block completion |
|
||||
| [Warning] | Error | Failures and exceptions |
|
||||
| [Parallel] | Parallel | Entering, branch status, joining |
|
||||
| [Loop] | Loop | Iteration, condition evaluation |
|
||||
| [Pipeline] | Pipeline | Stage progress |
|
||||
| [Try] | Error handling | Try/catch/finally |
|
||||
| [Flow] | Flow | Condition evaluation results |
|
||||
| [Frame+] | Call Stack | Push new frame (block invocation) |
|
||||
| [Frame-] | Call Stack | Pop frame (block completion) |
|
||||
| Marker | Category | Usage |
|
||||
| ---------- | -------------- | --------------------------------------- |
|
||||
| [Program] | Program | Start, end, definition collection |
|
||||
| [Position] | Position | Current statement being executed |
|
||||
| [Binding] | Binding | Variable assignment or update |
|
||||
| [Input] | Input | Receiving inputs from caller |
|
||||
| [Output] | Output | Producing outputs for caller |
|
||||
| [Import] | Import | Fetching and invoking imported programs |
|
||||
| [Success] | Success | Session or block completion |
|
||||
| [Warning] | Error | Failures and exceptions |
|
||||
| [Parallel] | Parallel | Entering, branch status, joining |
|
||||
| [Loop] | Loop | Iteration, condition evaluation |
|
||||
| [Pipeline] | Pipeline | Stage progress |
|
||||
| [Try] | Error handling | Try/catch/finally |
|
||||
| [Flow] | Flow | Condition evaluation results |
|
||||
| [Frame+] | Call Stack | Push new frame (block invocation) |
|
||||
| [Frame-] | Call Stack | Pop frame (block completion) |
|
||||
|
||||
---
|
||||
|
||||
@@ -185,6 +185,7 @@ Track block invocations with frame markers:
|
||||
```
|
||||
|
||||
**Key points:**
|
||||
|
||||
- Each `[Frame+]` must have a matching `[Frame-]`
|
||||
- `execution_id` uniquely identifies each invocation
|
||||
- `depth` shows call stack depth (1 = first level)
|
||||
@@ -236,13 +237,14 @@ For variable resolution across scopes:
|
||||
|
||||
When passing context to sessions, format appropriately:
|
||||
|
||||
| Context Size | Strategy |
|
||||
|--------------|----------|
|
||||
| < 2000 chars | Pass verbatim |
|
||||
| Context Size | Strategy |
|
||||
| --------------- | ----------------------- |
|
||||
| < 2000 chars | Pass verbatim |
|
||||
| 2000-8000 chars | Summarize to key points |
|
||||
| > 8000 chars | Extract essentials only |
|
||||
| > 8000 chars | Extract essentials only |
|
||||
|
||||
**Format:**
|
||||
|
||||
```
|
||||
Context provided:
|
||||
---
|
||||
@@ -274,6 +276,7 @@ loop until **analysis complete** (max: 3):
|
||||
```
|
||||
|
||||
**Narration:**
|
||||
|
||||
```
|
||||
[Program] Program Start
|
||||
Collecting definitions...
|
||||
@@ -322,20 +325,20 @@ loop until **analysis complete** (max: 3):
|
||||
|
||||
The VM must track these state categories in narration:
|
||||
|
||||
| Category | What to Track | Example |
|
||||
|----------|---------------|---------|
|
||||
| **Import Registry** | Imported programs and aliases | `research: @alice/research` |
|
||||
| **Agent Registry** | All agent definitions | `researcher: {model: sonnet, prompt: "..."}` |
|
||||
| **Block Registry** | All block definitions (hoisted) | `review: {params: [topic], body: [...]}` |
|
||||
| **Input Bindings** | Inputs received from caller | `topic = "quantum computing"` |
|
||||
| **Output Bindings** | Outputs to return to caller | `findings = "Research shows..."` |
|
||||
| **Variable Bindings** | Name -> value mapping (with execution_id) | `result = "..." (execution_id: 3)` |
|
||||
| **Variable Mutability** | Which are `let` vs `const` vs `output` | `research: let, findings: output` |
|
||||
| **Execution Position** | Current statement index | Statement 3 of 7 |
|
||||
| **Loop State** | Counter, max, condition | Iteration 2 of max 5 |
|
||||
| **Parallel State** | Branches, results, strategy | `{a: complete, b: pending}` |
|
||||
| **Error State** | Exception, retry count | Retry 2 of 3, error: "timeout" |
|
||||
| **Call Stack** | Stack of execution frames | See below |
|
||||
| Category | What to Track | Example |
|
||||
| ----------------------- | ----------------------------------------- | -------------------------------------------- |
|
||||
| **Import Registry** | Imported programs and aliases | `research: @alice/research` |
|
||||
| **Agent Registry** | All agent definitions | `researcher: {model: sonnet, prompt: "..."}` |
|
||||
| **Block Registry** | All block definitions (hoisted) | `review: {params: [topic], body: [...]}` |
|
||||
| **Input Bindings** | Inputs received from caller | `topic = "quantum computing"` |
|
||||
| **Output Bindings** | Outputs to return to caller | `findings = "Research shows..."` |
|
||||
| **Variable Bindings** | Name -> value mapping (with execution_id) | `result = "..." (execution_id: 3)` |
|
||||
| **Variable Mutability** | Which are `let` vs `const` vs `output` | `research: let, findings: output` |
|
||||
| **Execution Position** | Current statement index | Statement 3 of 7 |
|
||||
| **Loop State** | Counter, max, condition | Iteration 2 of max 5 |
|
||||
| **Parallel State** | Branches, results, strategy | `{a: complete, b: pending}` |
|
||||
| **Error State** | Exception, retry count | Retry 2 of 3, error: "timeout" |
|
||||
| **Call Stack** | Stack of execution frames | See below |
|
||||
|
||||
### Call Stack State
|
||||
|
||||
@@ -349,6 +352,7 @@ For block invocations, track the full call stack:
|
||||
```
|
||||
|
||||
Each frame tracks:
|
||||
|
||||
- `execution_id`: Unique ID for this invocation
|
||||
- `block`: Name of the block
|
||||
- `depth`: Position in call stack
|
||||
|
||||
@@ -21,19 +21,20 @@ This document describes how the OpenProse VM tracks execution state using a **Po
|
||||
## Prerequisites
|
||||
|
||||
**Requires:**
|
||||
|
||||
1. The `psql` command-line tool must be available in your PATH
|
||||
2. A running PostgreSQL server (local, Docker, or cloud)
|
||||
|
||||
### Installing psql
|
||||
|
||||
| Platform | Command | Notes |
|
||||
|----------|---------|-------|
|
||||
| macOS (Homebrew) | `brew install libpq && brew link --force libpq` | Client-only; no server |
|
||||
| macOS (Postgres.app) | Download from https://postgresapp.com | Full install with GUI |
|
||||
| Debian/Ubuntu | `apt install postgresql-client` | Client-only |
|
||||
| Fedora/RHEL | `dnf install postgresql` | Client-only |
|
||||
| Arch Linux | `pacman -S postgresql-libs` | Client-only |
|
||||
| Windows | `winget install PostgreSQL.PostgreSQL` | Full installer |
|
||||
| Platform | Command | Notes |
|
||||
| -------------------- | ----------------------------------------------- | ---------------------- |
|
||||
| macOS (Homebrew) | `brew install libpq && brew link --force libpq` | Client-only; no server |
|
||||
| macOS (Postgres.app) | Download from https://postgresapp.com | Full install with GUI |
|
||||
| Debian/Ubuntu | `apt install postgresql-client` | Client-only |
|
||||
| Fedora/RHEL | `dnf install postgresql` | Client-only |
|
||||
| Arch Linux | `pacman -S postgresql-libs` | Client-only |
|
||||
| Windows | `winget install PostgreSQL.PostgreSQL` | Full installer |
|
||||
|
||||
After installation, verify:
|
||||
|
||||
@@ -70,6 +71,7 @@ PostgreSQL state provides:
|
||||
- Create a **limited-privilege user** with access only to the `openprose` schema
|
||||
|
||||
**Recommended setup:**
|
||||
|
||||
```sql
|
||||
-- Create dedicated user with minimal privileges
|
||||
CREATE USER openprose_agent WITH PASSWORD 'changeme';
|
||||
@@ -84,13 +86,13 @@ GRANT ALL ON SCHEMA openprose TO openprose_agent;
|
||||
|
||||
PostgreSQL state is for **power users** with specific scale or collaboration needs:
|
||||
|
||||
| Need | PostgreSQL Helps |
|
||||
|------|------------------|
|
||||
| >5 parallel branches writing simultaneously | SQLite locks; PostgreSQL doesn't |
|
||||
| External dashboards querying state | PostgreSQL is designed for concurrent readers |
|
||||
| Team collaboration on long workflows | Shared network access; no file sync needed |
|
||||
| Outputs exceeding 1GB | Bulk ingestion; no single-file bottleneck |
|
||||
| Mission-critical workflows (hours/days) | Robust durability; point-in-time recovery |
|
||||
| Need | PostgreSQL Helps |
|
||||
| ------------------------------------------- | --------------------------------------------- |
|
||||
| >5 parallel branches writing simultaneously | SQLite locks; PostgreSQL doesn't |
|
||||
| External dashboards querying state | PostgreSQL is designed for concurrent readers |
|
||||
| Team collaboration on long workflows | Shared network access; no file sync needed |
|
||||
| Outputs exceeding 1GB | Bulk ingestion; no single-file bottleneck |
|
||||
| Mission-critical workflows (hours/days) | Robust durability; point-in-time recovery |
|
||||
|
||||
**If none of these apply, use filesystem or SQLite state.** They're simpler and sufficient for 99% of programs.
|
||||
|
||||
@@ -187,11 +189,11 @@ echo "OPENPROSE_POSTGRES_URL=postgresql:///myproject" >> .prose/.env
|
||||
|
||||
For team collaboration or production:
|
||||
|
||||
| Provider | Free Tier | Cold Start | Best For |
|
||||
|----------|-----------|------------|----------|
|
||||
| **Neon** | 0.5GB, auto-suspend | 1-3s | Development, testing |
|
||||
| **Supabase** | 500MB, no auto-suspend | None | Projects needing auth/storage |
|
||||
| **Railway** | $5/mo credit | None | Simple production deploys |
|
||||
| Provider | Free Tier | Cold Start | Best For |
|
||||
| ------------ | ---------------------- | ---------- | ----------------------------- |
|
||||
| **Neon** | 0.5GB, auto-suspend | 1-3s | Development, testing |
|
||||
| **Supabase** | 500MB, no auto-suspend | None | Projects needing auth/storage |
|
||||
| **Railway** | $5/mo credit | None | Simple production deploys |
|
||||
|
||||
```bash
|
||||
# Example: Neon
|
||||
@@ -246,17 +248,17 @@ This section defines **who does what**. This is the contract between the VM and
|
||||
|
||||
The VM (the orchestrating agent running the .prose program) is responsible for:
|
||||
|
||||
| Responsibility | Description |
|
||||
|----------------|-------------|
|
||||
| **Schema initialization** | Create `openprose` schema and tables at run start |
|
||||
| **Run registration** | Store the program source and metadata |
|
||||
| **Execution tracking** | Update position, status, and timing as statements execute |
|
||||
| **Subagent spawning** | Spawn sessions via Task tool with database instructions |
|
||||
| **Parallel coordination** | Track branch status, implement join strategies |
|
||||
| **Loop management** | Track iteration counts, evaluate conditions |
|
||||
| **Error aggregation** | Record failures, manage retry state |
|
||||
| **Context preservation** | Maintain sufficient narration in the main thread |
|
||||
| **Completion detection** | Mark the run as complete when finished |
|
||||
| Responsibility | Description |
|
||||
| ------------------------- | --------------------------------------------------------- |
|
||||
| **Schema initialization** | Create `openprose` schema and tables at run start |
|
||||
| **Run registration** | Store the program source and metadata |
|
||||
| **Execution tracking** | Update position, status, and timing as statements execute |
|
||||
| **Subagent spawning** | Spawn sessions via Task tool with database instructions |
|
||||
| **Parallel coordination** | Track branch status, implement join strategies |
|
||||
| **Loop management** | Track iteration counts, evaluate conditions |
|
||||
| **Error aggregation** | Record failures, manage retry state |
|
||||
| **Context preservation** | Maintain sufficient narration in the main thread |
|
||||
| **Completion detection** | Mark the run as complete when finished |
|
||||
|
||||
**Critical:** The VM must preserve enough context in its own conversation to understand execution state without re-reading the entire database. The database is for coordination and persistence, not a replacement for working memory.
|
||||
|
||||
@@ -264,13 +266,13 @@ The VM (the orchestrating agent running the .prose program) is responsible for:
|
||||
|
||||
Subagents (sessions spawned by the VM) are responsible for:
|
||||
|
||||
| Responsibility | Description |
|
||||
|----------------|-------------|
|
||||
| **Writing own outputs** | Insert/update their binding in the `bindings` table |
|
||||
| **Memory management** | For persistent agents: read and update their memory record |
|
||||
| **Segment recording** | For persistent agents: append segment history |
|
||||
| Responsibility | Description |
|
||||
| ----------------------- | ----------------------------------------------------------------- |
|
||||
| **Writing own outputs** | Insert/update their binding in the `bindings` table |
|
||||
| **Memory management** | For persistent agents: read and update their memory record |
|
||||
| **Segment recording** | For persistent agents: append segment history |
|
||||
| **Attachment handling** | Write large outputs to `attachments/` directory, store path in DB |
|
||||
| **Atomic writes** | Use transactions when updating multiple related records |
|
||||
| **Atomic writes** | Use transactions when updating multiple related records |
|
||||
|
||||
**Critical:** Subagents write ONLY to `bindings`, `agents`, and `agent_segments` tables. The VM owns the `execution` table entirely. Completion signaling happens through the substrate (Task tool return), not database updates.
|
||||
|
||||
@@ -279,6 +281,7 @@ Subagents (sessions spawned by the VM) are responsible for:
|
||||
**What subagents return to the VM:** A confirmation message with the binding location—not the full content:
|
||||
|
||||
**Root scope:**
|
||||
|
||||
```
|
||||
Binding written: research
|
||||
Location: openprose.bindings WHERE name='research' AND run_id='20260116-143052-a7b3c9' AND execution_id IS NULL
|
||||
@@ -286,6 +289,7 @@ Summary: AI safety research covering alignment, robustness, and interpretability
|
||||
```
|
||||
|
||||
**Inside block invocation:**
|
||||
|
||||
```
|
||||
Binding written: result
|
||||
Location: openprose.bindings WHERE name='result' AND run_id='20260116-143052-a7b3c9' AND execution_id=43
|
||||
@@ -297,12 +301,12 @@ The VM tracks locations, not values. This keeps the VM's context lean and enable
|
||||
|
||||
### Shared Concerns
|
||||
|
||||
| Concern | Who Handles |
|
||||
|---------|-------------|
|
||||
| Concern | Who Handles |
|
||||
| ---------------- | ------------------------------------------------------------------ |
|
||||
| Schema evolution | Either (use `CREATE TABLE IF NOT EXISTS`, `ALTER TABLE` as needed) |
|
||||
| Custom tables | Either (prefix with `x_` for extensions) |
|
||||
| Indexing | Either (add indexes for frequently-queried columns) |
|
||||
| Cleanup | VM (at run end, optionally delete old data) |
|
||||
| Custom tables | Either (prefix with `x_` for extensions) |
|
||||
| Indexing | Either (add indexes for frequently-queried columns) |
|
||||
| Cleanup | VM (at run end, optionally delete old data) |
|
||||
|
||||
---
|
||||
|
||||
@@ -601,12 +605,12 @@ Even with PostgreSQL state, the VM should narrate key events in its conversation
|
||||
|
||||
### Why Both?
|
||||
|
||||
| Purpose | Mechanism |
|
||||
|---------|-----------|
|
||||
| **Working memory** | Conversation narration (what the VM "remembers" without re-querying) |
|
||||
| **Durable state** | PostgreSQL database (survives context limits, enables resumption) |
|
||||
| **Subagent coordination** | PostgreSQL database (shared access point) |
|
||||
| **Debugging/inspection** | PostgreSQL database (queryable history) |
|
||||
| Purpose | Mechanism |
|
||||
| ------------------------- | -------------------------------------------------------------------- |
|
||||
| **Working memory** | Conversation narration (what the VM "remembers" without re-querying) |
|
||||
| **Durable state** | PostgreSQL database (survives context limits, enables resumption) |
|
||||
| **Subagent coordination** | PostgreSQL database (shared access point) |
|
||||
| **Debugging/inspection** | PostgreSQL database (queryable history) |
|
||||
|
||||
The narration is the VM's "mental model" of execution. The database is the "source of truth" for resumption and inspection.
|
||||
|
||||
@@ -717,6 +721,7 @@ PRIMARY KEY (name, COALESCE(run_id, '__project__'))
|
||||
```
|
||||
|
||||
This means:
|
||||
|
||||
- `name='advisor', run_id=NULL` has PK `('advisor', '__project__')`
|
||||
- `name='advisor', run_id='20260116-143052-a7b3c9'` has PK `('advisor', '20260116-143052-a7b3c9')`
|
||||
|
||||
@@ -724,10 +729,10 @@ The same agent name can exist as both project-scoped and execution-scoped withou
|
||||
|
||||
### Query Patterns
|
||||
|
||||
| Scope | Query |
|
||||
|-------|-------|
|
||||
| Scope | Query |
|
||||
| ---------------- | ------------------------------------------------ |
|
||||
| Execution-scoped | `WHERE name = 'captain' AND run_id = '{RUN_ID}'` |
|
||||
| Project-scoped | `WHERE name = 'advisor' AND run_id IS NULL` |
|
||||
| Project-scoped | `WHERE name = 'advisor' AND run_id IS NULL` |
|
||||
|
||||
### Project-Scoped Memory Guidelines
|
||||
|
||||
@@ -841,20 +846,20 @@ The database is your workspace. Use it.
|
||||
|
||||
## Comparison with Other Modes
|
||||
|
||||
| Aspect | filesystem.md | in-context.md | sqlite.md | postgres.md |
|
||||
|--------|---------------|---------------|-----------|-------------|
|
||||
| **State location** | `.prose/runs/{id}/` files | Conversation history | `.prose/runs/{id}/state.db` | PostgreSQL database |
|
||||
| **Queryable** | Via file reads | No | Yes (SQL) | Yes (SQL) |
|
||||
| **Atomic updates** | No | N/A | Yes (transactions) | Yes (ACID) |
|
||||
| **Concurrent writes** | Yes (different files) | N/A | **No (table locks)** | **Yes (row locks)** |
|
||||
| **Network access** | No | No | No | **Yes** |
|
||||
| **Team collaboration** | Via file sync | No | Via file sync | **Yes** |
|
||||
| **Schema flexibility** | Rigid file structure | N/A | Flexible | Very flexible (JSONB) |
|
||||
| **Resumption** | Read state.md | Re-read conversation | Query database | Query database |
|
||||
| **Complexity ceiling** | High | Low (<30 statements) | High | **Very high** |
|
||||
| **Dependency** | None | None | sqlite3 CLI | psql CLI + PostgreSQL |
|
||||
| **Setup friction** | Zero | Zero | Low | Medium-High |
|
||||
| **Status** | Stable | Stable | Experimental | **Experimental** |
|
||||
| Aspect | filesystem.md | in-context.md | sqlite.md | postgres.md |
|
||||
| ---------------------- | ------------------------- | -------------------- | --------------------------- | --------------------- |
|
||||
| **State location** | `.prose/runs/{id}/` files | Conversation history | `.prose/runs/{id}/state.db` | PostgreSQL database |
|
||||
| **Queryable** | Via file reads | No | Yes (SQL) | Yes (SQL) |
|
||||
| **Atomic updates** | No | N/A | Yes (transactions) | Yes (ACID) |
|
||||
| **Concurrent writes** | Yes (different files) | N/A | **No (table locks)** | **Yes (row locks)** |
|
||||
| **Network access** | No | No | No | **Yes** |
|
||||
| **Team collaboration** | Via file sync | No | Via file sync | **Yes** |
|
||||
| **Schema flexibility** | Rigid file structure | N/A | Flexible | Very flexible (JSONB) |
|
||||
| **Resumption** | Read state.md | Re-read conversation | Query database | Query database |
|
||||
| **Complexity ceiling** | High | Low (<30 statements) | High | **Very high** |
|
||||
| **Dependency** | None | None | sqlite3 CLI | psql CLI + PostgreSQL |
|
||||
| **Setup friction** | Zero | Zero | Low | Medium-High |
|
||||
| **Status** | Stable | Stable | Experimental | **Experimental** |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -21,11 +21,11 @@ This document describes how the OpenProse VM tracks execution state using a **SQ
|
||||
|
||||
**Requires:** The `sqlite3` command-line tool must be available in your PATH.
|
||||
|
||||
| Platform | Installation |
|
||||
|----------|--------------|
|
||||
| macOS | Pre-installed |
|
||||
| Linux | `apt install sqlite3` / `dnf install sqlite3` / etc. |
|
||||
| Windows | `winget install SQLite.SQLite` or download from sqlite.org |
|
||||
| Platform | Installation |
|
||||
| -------- | ---------------------------------------------------------- |
|
||||
| macOS | Pre-installed |
|
||||
| Linux | `apt install sqlite3` / `dnf install sqlite3` / etc. |
|
||||
| Windows | `winget install SQLite.SQLite` or download from sqlite.org |
|
||||
|
||||
If `sqlite3` is not available, the VM will fall back to filesystem state and warn the user.
|
||||
|
||||
@@ -93,17 +93,17 @@ This section defines **who does what**. This is the contract between the VM and
|
||||
|
||||
The VM (the orchestrating agent running the .prose program) is responsible for:
|
||||
|
||||
| Responsibility | Description |
|
||||
|----------------|-------------|
|
||||
| **Database creation** | Create `state.db` and initialize core tables at run start |
|
||||
| **Program registration** | Store the program source and metadata |
|
||||
| **Execution tracking** | Update position, status, and timing as statements execute |
|
||||
| **Subagent spawning** | Spawn sessions via Task tool with database path and instructions |
|
||||
| **Parallel coordination** | Track branch status, implement join strategies |
|
||||
| **Loop management** | Track iteration counts, evaluate conditions |
|
||||
| **Error aggregation** | Record failures, manage retry state |
|
||||
| **Context preservation** | Maintain sufficient narration in the main conversation thread so execution can be understood and resumed |
|
||||
| **Completion detection** | Mark the run as complete when finished |
|
||||
| Responsibility | Description |
|
||||
| ------------------------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| **Database creation** | Create `state.db` and initialize core tables at run start |
|
||||
| **Program registration** | Store the program source and metadata |
|
||||
| **Execution tracking** | Update position, status, and timing as statements execute |
|
||||
| **Subagent spawning** | Spawn sessions via Task tool with database path and instructions |
|
||||
| **Parallel coordination** | Track branch status, implement join strategies |
|
||||
| **Loop management** | Track iteration counts, evaluate conditions |
|
||||
| **Error aggregation** | Record failures, manage retry state |
|
||||
| **Context preservation** | Maintain sufficient narration in the main conversation thread so execution can be understood and resumed |
|
||||
| **Completion detection** | Mark the run as complete when finished |
|
||||
|
||||
**Critical:** The VM must preserve enough context in its own conversation to understand execution state without re-reading the entire database. The database is for coordination and persistence, not a replacement for working memory.
|
||||
|
||||
@@ -111,13 +111,13 @@ The VM (the orchestrating agent running the .prose program) is responsible for:
|
||||
|
||||
Subagents (sessions spawned by the VM) are responsible for:
|
||||
|
||||
| Responsibility | Description |
|
||||
|----------------|-------------|
|
||||
| **Writing own outputs** | Insert/update their binding in the `bindings` table |
|
||||
| **Memory management** | For persistent agents: read and update their memory record |
|
||||
| **Segment recording** | For persistent agents: append segment history |
|
||||
| Responsibility | Description |
|
||||
| ----------------------- | ----------------------------------------------------------------- |
|
||||
| **Writing own outputs** | Insert/update their binding in the `bindings` table |
|
||||
| **Memory management** | For persistent agents: read and update their memory record |
|
||||
| **Segment recording** | For persistent agents: append segment history |
|
||||
| **Attachment handling** | Write large outputs to `attachments/` directory, store path in DB |
|
||||
| **Atomic writes** | Use transactions when updating multiple related records |
|
||||
| **Atomic writes** | Use transactions when updating multiple related records |
|
||||
|
||||
**Critical:** Subagents write ONLY to `bindings`, `agents`, and `agent_segments` tables. The VM owns the `execution` table entirely. Completion signaling happens through the substrate (Task tool return), not database updates.
|
||||
|
||||
@@ -126,6 +126,7 @@ Subagents (sessions spawned by the VM) are responsible for:
|
||||
**What subagents return to the VM:** A confirmation message with the binding location—not the full content:
|
||||
|
||||
**Root scope:**
|
||||
|
||||
```
|
||||
Binding written: research
|
||||
Location: .prose/runs/20260116-143052-a7b3c9/state.db (bindings table, name='research', execution_id=NULL)
|
||||
@@ -133,6 +134,7 @@ Summary: AI safety research covering alignment, robustness, and interpretability
|
||||
```
|
||||
|
||||
**Inside block invocation:**
|
||||
|
||||
```
|
||||
Binding written: result
|
||||
Location: .prose/runs/20260116-143052-a7b3c9/state.db (bindings table, name='result', execution_id=43)
|
||||
@@ -144,12 +146,12 @@ The VM tracks locations, not values. This keeps the VM's context lean and enable
|
||||
|
||||
### Shared Concerns
|
||||
|
||||
| Concern | Who Handles |
|
||||
|---------|-------------|
|
||||
| Concern | Who Handles |
|
||||
| ---------------- | ------------------------------------------------------------------ |
|
||||
| Schema evolution | Either (use `CREATE TABLE IF NOT EXISTS`, `ALTER TABLE` as needed) |
|
||||
| Custom tables | Either (prefix with `x_` for extensions) |
|
||||
| Indexing | Either (add indexes for frequently-queried columns) |
|
||||
| Cleanup | VM (at run end, optionally vacuum) |
|
||||
| Custom tables | Either (prefix with `x_` for extensions) |
|
||||
| Indexing | Either (add indexes for frequently-queried columns) |
|
||||
| Cleanup | VM (at run end, optionally vacuum) |
|
||||
|
||||
---
|
||||
|
||||
@@ -390,12 +392,12 @@ Even with SQLite state, the VM should narrate key events in its conversation:
|
||||
|
||||
### Why Both?
|
||||
|
||||
| Purpose | Mechanism |
|
||||
|---------|-----------|
|
||||
| **Working memory** | Conversation narration (what the VM "remembers" without re-querying) |
|
||||
| **Durable state** | SQLite database (survives context limits, enables resumption) |
|
||||
| **Subagent coordination** | SQLite database (shared access point) |
|
||||
| **Debugging/inspection** | SQLite database (queryable history) |
|
||||
| Purpose | Mechanism |
|
||||
| ------------------------- | -------------------------------------------------------------------- |
|
||||
| **Working memory** | Conversation narration (what the VM "remembers" without re-querying) |
|
||||
| **Durable state** | SQLite database (survives context limits, enables resumption) |
|
||||
| **Subagent coordination** | SQLite database (shared access point) |
|
||||
| **Debugging/inspection** | SQLite database (queryable history) |
|
||||
|
||||
The narration is the VM's "mental model" of execution. The database is the "source of truth" for resumption and inspection.
|
||||
|
||||
@@ -544,16 +546,16 @@ The database is your workspace. Use it.
|
||||
|
||||
## Comparison with Other Modes
|
||||
|
||||
| Aspect | filesystem.md | in-context.md | sqlite.md |
|
||||
|--------|---------------|---------------|-----------|
|
||||
| **State location** | `.prose/runs/{id}/` files | Conversation history | `.prose/runs/{id}/state.db` |
|
||||
| **Queryable** | Via file reads | No | Yes (SQL) |
|
||||
| **Atomic updates** | No | N/A | Yes (transactions) |
|
||||
| **Schema flexibility** | Rigid file structure | N/A | Flexible (add tables/columns) |
|
||||
| **Resumption** | Read state.md | Re-read conversation | Query database |
|
||||
| **Complexity ceiling** | High | Low (<30 statements) | High |
|
||||
| **Dependency** | None | None | sqlite3 CLI |
|
||||
| **Status** | Stable | Stable | **Experimental** |
|
||||
| Aspect | filesystem.md | in-context.md | sqlite.md |
|
||||
| ---------------------- | ------------------------- | -------------------- | ----------------------------- |
|
||||
| **State location** | `.prose/runs/{id}/` files | Conversation history | `.prose/runs/{id}/state.db` |
|
||||
| **Queryable** | Via file reads | No | Yes (SQL) |
|
||||
| **Atomic updates** | No | N/A | Yes (transactions) |
|
||||
| **Schema flexibility** | Rigid file structure | N/A | Flexible (add tables/columns) |
|
||||
| **Resumption** | Read state.md | Re-read conversation | Query database |
|
||||
| **Complexity ceiling** | High | Low (<30 statements) | High |
|
||||
| **Dependency** | None | None | sqlite3 CLI |
|
||||
| **Status** | Stable | Stable | **Experimental** |
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user