loudmouth-ai 0.1.0 → 0.2.0

package/extensions/open-prose/skills/prose/primitives/session.md

@@ -1,587 +0,0 @@
----
-role: session-context-management
-summary: |
-  Guidelines for subagents on context handling, state management, and memory compaction.
-  This file is loaded into all subagent sessions at start time to ensure consistent
-  behavior around state persistence and context flow.
-see-also:
-  - ../prose.md: VM execution semantics
-  - ../compiler.md: Full language specification
-  - ../state/filesystem.md: File-system state management (default)
-  - ../state/in-context.md: In-context state management (on request)
-  - ../state/sqlite.md: SQLite state management (experimental)
-  - ../state/postgres.md: PostgreSQL state management (experimental)
----
-
-# Session Context Management
-
-You are a subagent operating within an OpenProse program. This document explains how to work with the context you receive and how to preserve state for future sessions.
-
----
-
-## 1. Understanding Your Context Layers
-
-When you start, you receive context from multiple sources. Understand what each represents:
-
-### 1.1 Outer Agent State
-
-The **outer agent state** is context from the orchestrating VM or parent agent. It tells you:
-
-- What program is running
-- Where you are in the execution flow
-- What has happened in prior steps
-
-Look for markers like:
-
-```
-## Execution Context
-Program: feature-implementation.prose
-Current phase: Implementation
-Prior steps completed: [plan, design]
-```
-
-**How to use it:** This orients you. You're not starting from scratch—you're continuing work that's already in progress. Reference prior steps when relevant.
-
-### 1.2 Persistent Agent Memory
-
-If you are a **persistent agent**, you'll receive a memory file with your prior observations and decisions. This is YOUR accumulated knowledge from previous segments.
-
-Look for:
-
-```
-## Agent Memory: [your-name]
-```
-
-**How to use it:** This is your continuity. You reviewed something yesterday; you remember that review today. Reference your prior decisions. Build on your accumulated understanding. Don't contradict yourself without acknowledging the change.
-
-### 1.3 Task Context
-
-The **task context** is the specific input for THIS session—the code to review, the plan to evaluate, the feature to implement.
-
-Look for:
-
-```
-## Task Context
-```
-
-or
-
-```
-Context provided:
----
-[specific content]
----
-```
-
-**How to use it:** This is what you're working on RIGHT NOW. Your primary focus. The other context layers inform how you approach this.
-
-### 1.4 Layering Order
-
-When context feels overwhelming, process in this order:
-
-1. **Skim outer state** → Where am I in the bigger picture?
-2. **Read your memory** → What do I already know?
-3. **Focus on task context** → What am I doing right now?
-4. **Synthesize** → How does my prior knowledge inform this task?
-
-### 1.5 Execution Scope (Block Invocations)
-
-If you're running inside a block invocation, you'll receive execution scope information:
-
-```
-Execution scope:
-  execution_id: 43
-  block: process
-  depth: 3
-  parent_execution_id: 42
-```
-
-**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) |
-
-**How to use it:**
-
-1. **Include in your binding output**: When writing bindings, include the `execution_id` in the filename and frontmatter so the VM can track scope correctly.
-
-2. **Understand variable isolation**: Your bindings won't collide with other invocations of the same block. If the block calls itself recursively, each invocation has its own `execution_id`.
-
-3. **Context references are pre-resolved**: The VM resolves variable references before passing context to you. You don't need to walk the scope chain—the VM already did.
-
-**Example:** If a recursive `process` block is at depth 5, there are 5 separate `execution_id` values, each with their own local bindings. Your session only sees the current frame's context.
-
----
-
-## 2. Working with Persistent State
-
-If you're a persistent agent, you maintain state across sessions via a memory file.
-
-### Two Distinct Outputs
-
-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 |
-
-**The binding is task-specific.** If you're asked to "review the plan," the binding contains your review.
-
-**The memory is agent-specific.** It contains your accumulated understanding, decisions, and concerns across ALL your invocations—not just this one.
-
-These are written to **different locations** and serve **different purposes**. Always write both.
-
-### 2.1 Reading Your Memory
-
-At session start, your memory file is provided. It contains:
-
-- **Current Understanding**: Your overall grasp of the project/task
-- **Decisions Made**: What you've decided and why
-- **Open Concerns**: Things you're watching for
-- **Recent Segments**: What happened in recent sessions
-
-**Read it carefully.** Your memory is your continuity. A persistent agent that ignores its memory is just a stateless agent with extra steps.
-
-### 2.2 Building on Prior Knowledge
-
-When you encounter something related to your memory:
-
-- Reference it explicitly: "In my previous review, I noted X..."
-- Build on it: "Given that I already approved the plan, I'm now checking implementation alignment..."
-- Update it if wrong: "I previously thought X, but now I see Y..."
-
-### 2.3 Maintaining Consistency
-
-Your decisions should be consistent across segments unless you explicitly change your position. If you approved a plan in segment 1, don't reject the same approach in segment 3 without acknowledging the change and explaining why.
-
----
-
-## 3. Memory Compaction Guidelines
-
-At the end of your session, you'll be asked to update your memory file. This is **compaction**—preserving what matters for future sessions.
-
-### 3.1 Compaction is NOT Summarization
-
-**Wrong approach:** "I reviewed the code and found some issues."
-
-This loses all useful information. A summary generalizes; compaction preserves specifics.
-
-**Right approach:** "Reviewed auth module (src/auth/login.ts:45-120). Found: (1) SQL injection risk in query builder line 67, (2) missing rate limiting on login endpoint, (3) good error handling pattern worth reusing. Requested fixes for #1 and #2, approved overall structure."
-
-### 3.2 What to Preserve
-
-Preserve **specific details** that future-you will need:
-
-| Preserve                     | Example                                                  |
-| ---------------------------- | -------------------------------------------------------- |
-| **Specific locations**       | "src/auth/login.ts:67" not "the auth code"               |
-| **Exact findings**           | "SQL injection in query builder" not "security issues"   |
-| **Decisions with rationale** | "Approved because X" not just "Approved"                 |
-| **Numbers and thresholds**   | "Coverage at 73%, target is 80%" not "coverage is low"   |
-| **Names and identifiers**    | "User.authenticate() method" not "the login function"    |
-| **Open questions**           | "Need to verify: does rate limiter apply to OAuth flow?" |
-
-### 3.3 What to Drop
-
-Drop information that won't help future sessions:
-
-| Drop             | Why                                                                         |
-| ---------------- | --------------------------------------------------------------------------- |
-| Reasoning chains | The conclusion matters, not how you got there                               |
-| False starts     | You considered X but chose Y—just record Y and a brief note about why not X |
-| Obvious context  | Don't repeat the task prompt back                                           |
-| Verbose quotes   | Reference by location, don't copy large blocks                              |
-
-### 3.4 Compaction Structure
-
-Update your memory file in this structure:
-
-```markdown
-## Current Understanding
-
-[What you know about the overall project/task—update, don't replace entirely]
-
-## Decisions Made
-
-[Append new decisions with dates and rationale]
-
-- [date]: [decision] — [why]
-
-## Open Concerns
-
-[Things to watch for in future sessions—add new, remove resolved]
-
-## Segment [N] Summary
-
-[What happened THIS session—specific, not general]
-
-- Reviewed: [what, where]
-- Found: [specific findings]
-- Decided: [specific decisions]
-- Next: [what should happen next]
-```
-
-### 3.5 Compaction Examples
-
-**Bad compaction (too general):**
-
-```
-## Segment 3 Summary
-Reviewed the implementation. Found some issues. Requested changes.
-```
-
-**Good compaction (specific and useful):**
-
-```
-## Segment 3 Summary
-- Reviewed: Step 2 implementation (UserService.ts, AuthController.ts)
-- Found:
-  - Missing null check in UserService.getById (line 34)
-  - AuthController.login not using the approved error format from segment 1
-  - Good: Transaction handling follows pattern I recommended
-- Decided: Request fixes for null check and error format before proceeding
-- Next: Re-review after fixes, then approve for step 3
-```
-
-### 3.6 The Specificity Test
-
-Before finalizing your compaction, ask: "If I read only this summary in a week, could I understand exactly what happened and make consistent follow-up decisions?"
-
-If the answer is no, add more specifics.
-
----
-
-## 4. Context Size Management
-
-### 4.1 When Your Memory Gets Long
-
-Over many segments, your memory file grows. When it becomes unwieldy:
-
-1. **Preserve recent segments in full** (last 2-3)
-2. **Compress older segments** into key decisions only
-3. **Archive ancient history** as bullet points
-
-```markdown
-## Recent Segments (full detail)
-
-[Segments 7-9]
-
-## Earlier Segments (compressed)
-
-- Segment 4-6: Completed initial implementation review, approved with minor fixes
-- Segment 1-3: Established review criteria, approved design doc
-
-## Key Historical Decisions
-
-- Chose JWT over session tokens (segment 2)
-- Established 80% coverage threshold (segment 1)
-```
-
-### 4.2 When Task Context is Large
-
-If you receive very large task context (big code blocks, long documents):
-
-1. **Don't try to hold it all** — reference by location
-2. **Note what you examined** — "Reviewed lines 1-200, focused on auth flow"
-3. **Record specific locations** — future sessions can re-examine if needed
-
----
-
-## 5. Signaling to the VM
-
-The OpenProse VM reads your output to determine next steps. Help it by being clear:
-
-### 5.1 Decision Signals
-
-When you make a decision that affects control flow, be explicit:
-
-```
-DECISION: Proceed with implementation
-RATIONALE: Plan addresses all concerns raised in previous review
-```
-
-or
-
-```
-DECISION: Request revision
-ISSUES:
-1. [specific issue]
-2. [specific issue]
-REQUIRED CHANGES: [what needs to happen]
-```
-
-### 5.2 Concern Signals
-
-When you notice something that doesn't block progress but should be tracked:
-
-```
-CONCERN: [specific concern]
-SEVERITY: [low/medium/high]
-TRACKING: [what to watch for]
-```
-
-### 5.3 Completion Signals
-
-When your segment is complete:
-
-```
-SEGMENT COMPLETE
-MEMORY UPDATES:
-- [what to add to Current Understanding]
-- [decisions to record]
-- [concerns to track]
-READY FOR: [what should happen next]
-```
-
----
-
-## 6. Writing Output Files
-
-When using file-based state (see `../state/filesystem.md`), the VM tells you where to write your output. You must write your results directly to the filesystem.
-
-### 6.1 Binding Output Files
-
-For regular sessions with output capture (`let x = session "..."`), write to the specified binding path:
-
-**Path format:** `.prose/runs/{run-id}/bindings/{name}.md`
-
-**Path format (inside block invocation):** `.prose/runs/{run-id}/bindings/{name}__{execution_id}.md`
-
-**File format:**
-
-````markdown
-# {name}
-
-kind: {let|const|output|input}
-execution_id: {id}  # Include if inside a block invocation (omit for root scope)
-
-source:
-
-```prose
-{the source code that created this binding}
-```
-````
-
----
-
-{Your actual output here}
-
-````
-
-**Example:**
-
-```markdown
-# research
-
-kind: let
-
-source:
-```prose
-let research = session: researcher
-  prompt: "Research AI safety"
-````
-
----
-
-AI safety research covers several key areas:
-
-1. **Alignment** - Ensuring AI systems pursue intended goals
-2. **Robustness** - Making systems resilient to edge cases
-3. **Interpretability** - Understanding how models make decisions
-
-Key papers include Amodei et al. (2016) on concrete problems...
-
-````
-
-### 6.2 Anonymous Session Output
-
-Sessions without explicit capture (`session "..."` without `let x =`) still produce output. These are written with `anon_` prefix:
-
-**Path:** `.prose/runs/{run-id}/bindings/anon_001.md`
-
-The VM assigns sequential numbers. Write the same format but note the binding came from an anonymous session:
-
-```markdown
-# anon_003
-
-kind: let
-
-source:
-```prose
-session "Analyze the codebase for security issues"
-````
-
----
-
-Security analysis found the following issues...
-
-````
-
-### 6.3 Persistent Agent Memory Output
-
-If you are a persistent agent (invoked with `resume:`), you have additional responsibilities:
-
-1. **Read your memory file first**
-2. **Process the task using memory + context**
-3. **Update your memory file** with compacted state
-4. **Write a segment file** recording this session
-
-**Memory file path:** `.prose/runs/{run-id}/agents/{name}/memory.md` (or `.prose/agents/{name}/` for project-scoped, or `~/.prose/agents/{name}/` for user-scoped)
-
-**Segment file path:** `.prose/runs/{run-id}/agents/{name}/{name}-{NNN}.md`
-
-**Memory file format:**
-
-```markdown
-# Agent Memory: {name}
-
-## Current Understanding
-
-{Your accumulated knowledge about the project/task}
-
-## Decisions Made
-
-- {date}: {decision} — {rationale}
-- {date}: {decision} — {rationale}
-
-## Open Concerns
-
-- {Concern 1}
-- {Concern 2}
-````
-
-**Segment file format:**
-
-```markdown
-# Segment {NNN}
-
-timestamp: {ISO8601}
-prompt: "{the prompt for this session}"
-
-## Summary
-
-- Reviewed: {what you examined}
-- Found: {specific findings}
-- Decided: {specific decisions}
-- Next: {what should happen next}
-```
-
-### 6.4 Output Writing Checklist
-
-Before completing your session:
-
-- [ ] Write your output to the specified binding path
-- [ ] If persistent agent: update memory.md
-- [ ] If persistent agent: write segment file
-- [ ] Use the exact file format specified
-- [ ] Include the source code snippet for traceability
-
----
-
-## 7. Returning to the VM
-
-When your session completes, you return a **confirmation message** to the VM—not your full output. The VM tracks pointers, not values.
-
-### 7.1 What to Return
-
-Your return message should include:
-
-```
-Binding written: {name}
-Location: {path or database coordinates}
-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
-Summary: Comprehensive AI safety research covering alignment, robustness, and interpretability with 15 key paper citations.
-```
-
-**Example (filesystem state, inside block invocation):**
-```
-Binding written: result
-Location: .prose/runs/20260116-143052-a7b3c9/bindings/result__43.md
-Execution ID: 43
-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'
-Summary: Comprehensive AI safety research covering alignment, robustness, and interpretability with 15 key paper citations.
-```
-
-**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
-Execution ID: 43
-Summary: Processed chunk into 3 sub-parts for recursive processing.
-```
-
-### 7.2 Why Pointers, Not Values
-
-The VM never holds full binding values in its working memory. This is intentional:
-
-1. **Scalability**: Bindings can be arbitrarily large (megabytes, even gigabytes)
-2. **RLM patterns**: Enables "environment as variable" where agents query state programmatically
-3. **Context efficiency**: The VM's context stays lean regardless of intermediate data size
-4. **Concurrent access**: Multiple agents can read/write different bindings simultaneously
-
-### 7.3 What NOT to Return
-
-Do NOT return your full output in the Task tool response. The VM will ignore it.
-
-**Bad:**
-```
-Here's my research:
-
-AI safety is a field that studies how to create artificial intelligence systems that are beneficial and avoid harmful outcomes. The field encompasses several key areas...
-[5000 more words]
-```
-
-**Good:**
-```
-Binding written: research
-Location: .prose/runs/20260116-143052-a7b3c9/bindings/research.md
-Summary: 5200-word AI safety overview covering alignment, robustness, interpretability, and governance with 15 citations.
-```
-
-### 7.4 For Persistent Agents
-
-If you're a persistent agent (invoked with `resume:`), also confirm your memory update:
-
-```
-Binding written: analysis
-Location: .prose/runs/20260116-143052-a7b3c9/bindings/analysis.md
-Summary: Risk assessment identifying 3 critical and 5 moderate concerns.
-
-Memory updated: captain
-Location: .prose/runs/20260116-143052-a7b3c9/agents/captain/memory.md
-Segment: captain-003.md
-```
-
----
-
-## Summary
-
-As a subagent in an OpenProse program:
-
-1. **Understand your context layers** — outer state, memory, task context
-2. **Read context by reference** — access binding files/database directly, load what you need
-3. **Build on your memory** — you have continuity, use it
-4. **Compact, don't summarize** — preserve specifics, drop reasoning chains
-5. **Signal clearly** — help the VM understand your decisions
-6. **Test your compaction** — would future-you understand exactly what happened?
-7. **Write outputs directly** — persist to the binding location you're given
-8. **Return pointers, not values** — the VM tracks locations, not content
-
-Your memory is what makes you persistent. The VM's efficiency depends on you writing outputs and returning confirmations—not dumping full content back through the substrate.