neuron-rs/neuron-lang/context.el

// context.el — Execution context tracking subsystem.
//
// ExecutionContexts are Neuron's working memory for multi-step tasks.
// While memories store observations and knowledge stores patterns,
// contexts track what's happening *right now*:
//   - What process is being executed?
//   - What steps have been taken?
//   - What files were touched?
//   - What decisions were made along the way?
//
// WHY track execution contexts?
// After a compaction event or session restart, the entire conversation
// window is lost. But an open context in Neuron persists. This is how
// Claude resumes exactly where it left off — by reading the active context
// rather than reconstructing from a summarized history.
//
// The Five Primitives mandate: begin_work() before any task with >2 steps.

from types import {
    Context,
    ContextStep,
    NeuronError,
}

// ── Public API ────────────────────────────────────────────────────────────────

// begin_work — open a new execution context.
//
// Call this before starting any task with more than 2 steps. Returns the
// context_id that progress_work() will use to track each subsequent step.
// The process_name should match a registered Process if one exists.
@manager
fn begin_work(
    process_name: String,
    description: String,
    objective: String,
    project: String,
) -> Result<Context, NeuronError> {
    let id = native_uuid()
    let now = native_now()
    let ctx = Context {
        id: id,
        process_name: process_name,
        description: description,
        objective: objective,
        project: project,
        status: "active",
        steps: [],
        file_refs: [],
        key_decisions: [],
        lessons_learned: [],
        created_at: now,
        updated_at: now,
    }
    native_store_context(ctx)?
    native_emit("context.opened", {"id": id, "process": process_name, "project": project})
    Ok(ctx)
}

// progress_work — record one step of an active execution context.
//
// Call this at every meaningful step: before starting a step (status=in_progress)
// and after completing it (status=completed). This granularity enables
// post-compact recovery at the exact next step.
//
// file_refs: absolute paths to files modified during this step.
// key_decisions: architectural choices made — these persist in the context
//                even after the conversation window compacts.
// lessons_learned: non-obvious outcomes worth capturing immediately.
@manager
fn progress_work(
    context_id: String,
    action: String,
    status: String,
    file_refs: [String],
    key_decisions: [String],
    lessons_learned: [String],
) -> Result<Context, NeuronError> {
    let ctx = native_get_context(context_id)?
    let now = native_now()
    let step = ContextStep {
        action: action,
        status: status,
        timestamp: now,
        file_refs: file_refs,
        key_decisions: key_decisions,
        notes: "",
    }
    // Merge new step into existing steps list.
    // Merge new file_refs and key_decisions into context-level lists.
    let updated = Context {
        id: ctx.id,
        process_name: ctx.process_name,
        description: ctx.description,
        objective: ctx.objective,
        project: ctx.project,
        status: ctx.status,
        steps: ctx.steps,
        file_refs: ctx.file_refs,
        key_decisions: ctx.key_decisions,
        lessons_learned: ctx.lessons_learned,
        created_at: ctx.created_at,
        updated_at: now,
    }
    native_update_context(updated)?
    native_emit("context.step_recorded", {
        "context_id": context_id,
        "action": action,
        "status": status,
    })
    Ok(updated)
}

// check_work — inspect the current state of an execution context.
//
// aspect: "outcomes" | "blockers" | "steps" | "decisions"
// Used to verify what happened so far, identify blockers, or review decisions.
@accessor
fn check_work(context_id: String, aspect: String) -> Result<Context, NeuronError> {
    let ctx = native_get_context(context_id)?
    // The aspect filter is applied by the caller / Axon response formatter.
    // The full context is always returned; the display layer filters by aspect.
    Ok(ctx)
}

// list_work — enumerate execution contexts with optional filters.
//
// Used at session start to find in-progress work that needs to resume.
@accessor
fn list_work(project: String, status: String) -> Result<[Context], NeuronError> {
    let results = activate Context where "project:{project} status:{status}"
    Ok(results)
}

// complete_work — finalize an execution context.
//
// Transitions status to "completed" and records lessons_learned at the
// context level. Call this when a task is fully done — not mid-task.
// Consolidate memories into knowledge BEFORE calling this.
@manager
fn complete_work(
    context_id: String,
    summary: String,
    lessons_learned: [String],
) -> Result<Context, NeuronError> {
    let ctx = native_get_context(context_id)?
    let now = native_now()
    let completed = Context {
        id: ctx.id,
        process_name: ctx.process_name,
        description: ctx.description,
        objective: summary,
        project: ctx.project,
        status: "completed",
        steps: ctx.steps,
        file_refs: ctx.file_refs,
        key_decisions: ctx.key_decisions,
        lessons_learned: lessons_learned,
        created_at: ctx.created_at,
        updated_at: now,
    }
    native_update_context(completed)?
    native_emit("context.completed", {"id": context_id, "project": ctx.project})
    Ok(completed)
}