aiwcli 0.9.0

package/dist/templates/_shared/lib/context/task_sync.py

@@ -0,0 +1,367 @@
+"""Task synchronization utilities for Claude native task integration.
+
+Provides bi-directional sync between:
+- Claude Code native TaskCreate/TaskUpdate/TaskList tools (ephemeral)
+- Persistent events.jsonl storage (source of truth)
+
+SESSION START (Hydrate):
+1. Read events.jsonl -> compute pending tasks
+2. Output instructions for Claude to recreate tasks via TaskCreate
+3. Claude's native TaskList now populated with persistent state
+
+DURING SESSION (Persist):
+1. Claude uses native TaskCreate/TaskUpdate
+2. CLAUDE.md instructs: after TaskUpdate, call append_event()
+3. Both systems stay in sync
+
+SESSION END:
+- events.jsonl already has everything
+- Next session will hydrate from it
+"""
+from pathlib import Path
+from typing import List, Optional
+
+from .event_log import (
+    get_current_state,
+    get_pending_tasks,
+    append_event,
+    Task,
+    EVENT_TASK_ADDED,
+    EVENT_TASK_STARTED,
+    EVENT_TASK_COMPLETED,
+    EVENT_TASK_BLOCKED,
+    EVENT_SESSION_STARTED,
+)
+from ..base.utils import eprint
+
+
+def _escape_string(s: str) -> str:
+    """
+    Escape a string for safe embedding in quoted YAML-like format.
+
+    Handles backslashes, newlines, tabs, and quotes.
+
+    Args:
+        s: Input string
+
+    Returns:
+        Escaped string safe for embedding in double quotes
+    """
+    if not s:
+        return ""
+    # Order matters: escape backslashes first, then other special chars
+    s = s.replace('\\', '\\\\')
+    s = s.replace('\n', '\\n')
+    s = s.replace('\r', '\\r')
+    s = s.replace('\t', '\\t')
+    s = s.replace('"', '\\"')
+    return s
+
+
+def generate_hydration_instructions(
+    context_id: str,
+    project_root: Path = None
+) -> str:
+    """
+    Generate instructions for Claude to recreate tasks from persistent storage.
+
+    Called by SessionStart hook when resuming a context.
+
+    Args:
+        context_id: Context identifier
+        project_root: Project root directory
+
+    Returns:
+        Formatted instructions for Claude to restore tasks
+    """
+    pending_tasks = get_pending_tasks(context_id, project_root)
+
+    if not pending_tasks:
+        return "No pending tasks to restore."
+
+    lines = [
+        "## Restoring Tasks from Previous Session",
+        "",
+        "Please recreate these tasks using TaskCreate:",
+        "",
+    ]
+
+    for task in pending_tasks:
+        lines.append(f"### Task: {task.subject}")
+        lines.append("")
+        lines.append("```")
+        lines.append("TaskCreate:")
+        # Escape special characters for YAML-like format
+        subject_escaped = _escape_string(task.subject)
+        lines.append(f'  subject: "{subject_escaped}"')
+        if task.description:
+            desc_escaped = _escape_string(task.description)
+            lines.append(f'  description: "{desc_escaped}"')
+        if task.active_form:
+            active_form_escaped = _escape_string(task.active_form)
+            lines.append(f'  activeForm: "{active_form_escaped}"')
+        lines.append(f'  metadata: {{"persistent_id": "{task.id}", "context": "{context_id}", "skip_persistence": true}}')
+        lines.append("```")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def generate_task_summary(context_id: str, project_root: Path = None) -> str:
+    """
+    Generate a summary of all tasks in a context.
+
+    Useful for status checks and completion suggestions.
+
+    Args:
+        context_id: Context identifier
+        project_root: Project root directory
+
+    Returns:
+        Formatted task summary
+    """
+    state = get_current_state(context_id, project_root)
+
+    if not state.tasks:
+        return "No tasks in this context."
+
+    completed = [t for t in state.tasks if t.status == "completed"]
+    pending = [t for t in state.tasks if t.status == "pending"]
+    in_progress = [t for t in state.tasks if t.status == "in_progress"]
+    blocked = [t for t in state.tasks if t.status == "blocked"]
+
+    lines = [
+        f"## Task Summary for: {context_id}",
+        "",
+        f"**Total:** {len(state.tasks)} tasks",
+        f"**Completed:** {len(completed)} | **In Progress:** {len(in_progress)} | **Pending:** {len(pending)} | **Blocked:** {len(blocked)}",
+        "",
+    ]
+
+    if completed:
+        lines.append("### Completed")
+        for t in completed:
+            lines.append(f"- [x] {t.subject}")
+        lines.append("")
+
+    if in_progress:
+        lines.append("### In Progress")
+        for t in in_progress:
+            lines.append(f"- [~] {t.subject}")
+        lines.append("")
+
+    if pending:
+        lines.append("### Pending")
+        for t in pending:
+            lines.append(f"- [ ] {t.subject}")
+        lines.append("")
+
+    if blocked:
+        lines.append("### Blocked")
+        for t in blocked:
+            lines.append(f"- [!] {t.subject}: {t.blocked_reason}")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def record_session_start(
+    context_id: str,
+    tasks_hydrated: Optional[List[str]] = None,
+    project_root: Path = None
+) -> bool:
+    """
+    Record a session_started event in the context's event log.
+
+    Called after SessionStart hook loads a context.
+
+    Args:
+        context_id: Context identifier
+        tasks_hydrated: List of task IDs that were restored
+        project_root: Project root directory
+
+    Returns:
+        True if event was recorded successfully
+    """
+    event_data = {}
+    if tasks_hydrated:
+        event_data["tasks_hydrated"] = tasks_hydrated
+
+    return append_event(
+        context_id,
+        EVENT_SESSION_STARTED,
+        project_root,
+        **event_data
+    )
+
+
+def record_task_created(
+    context_id: str,
+    task_id: str,
+    subject: str,
+    description: str = "",
+    active_form: str = "",
+    project_root: Path = None
+) -> bool:
+    """
+    Record a task_added event in the context's event log.
+
+    Called when Claude creates a new task via TaskCreate.
+
+    Args:
+        context_id: Context identifier
+        task_id: Persistent task ID (e.g., "aiw-1")
+        subject: Task subject (required)
+        description: Task description (optional)
+        active_form: Spinner text for in_progress status (optional)
+        project_root: Project root directory
+
+    Returns:
+        True if event was recorded successfully
+    """
+    event_data = {
+        "task_id": task_id,
+        "subject": subject,
+    }
+    if description:
+        event_data["description"] = description
+    if active_form:
+        event_data["activeForm"] = active_form
+
+    return append_event(
+        context_id,
+        EVENT_TASK_ADDED,
+        project_root,
+        **event_data
+    )
+
+
+def record_task_started(
+    context_id: str,
+    task_id: str,
+    project_root: Path = None
+) -> bool:
+    """
+    Record a task_started event in the context's event log.
+
+    Called when Claude starts working on a task.
+
+    Args:
+        context_id: Context identifier
+        task_id: Persistent task ID
+        project_root: Project root directory
+
+    Returns:
+        True if event was recorded successfully
+    """
+    return append_event(
+        context_id,
+        EVENT_TASK_STARTED,
+        project_root,
+        task_id=task_id
+    )
+
+
+def record_task_completed(
+    context_id: str,
+    task_id: str,
+    evidence: str,
+    work_summary: str = "",
+    files_changed: Optional[List[str]] = None,
+    commit_ref: str = "",
+    project_root: Path = None
+) -> bool:
+    """
+    Record a task_completed event in the context's event log.
+
+    Called when Claude completes a task.
+
+    Args:
+        context_id: Context identifier
+        task_id: Persistent task ID
+        evidence: Verification evidence (required)
+        work_summary: Summary of work done (optional)
+        files_changed: List of files modified (optional)
+        commit_ref: Git commit reference (optional)
+        project_root: Project root directory
+
+    Returns:
+        True if event was recorded successfully
+    """
+    event_data = {
+        "task_id": task_id,
+        "evidence": evidence,
+    }
+    if work_summary:
+        event_data["work_summary"] = work_summary
+    if files_changed:
+        event_data["files_changed"] = files_changed
+    if commit_ref:
+        event_data["commit_ref"] = commit_ref
+
+    return append_event(
+        context_id,
+        EVENT_TASK_COMPLETED,
+        project_root,
+        **event_data
+    )
+
+
+def record_task_blocked(
+    context_id: str,
+    task_id: str,
+    reason: str,
+    project_root: Path = None
+) -> bool:
+    """
+    Record a task_blocked event in the context's event log.
+
+    Called when a task becomes blocked.
+
+    Args:
+        context_id: Context identifier
+        task_id: Persistent task ID
+        reason: Reason for being blocked
+        project_root: Project root directory
+
+    Returns:
+        True if event was recorded successfully
+    """
+    return append_event(
+        context_id,
+        EVENT_TASK_BLOCKED,
+        project_root,
+        task_id=task_id,
+        reason=reason
+    )
+
+
+def generate_next_task_id(context_id: str, project_root: Path = None) -> str:
+    """
+    Generate the next sequential task ID for a context.
+
+    Task IDs follow the pattern: aiw-{n} where n starts at 1.
+
+    Args:
+        context_id: Context identifier
+        project_root: Project root directory
+
+    Returns:
+        Next available task ID (e.g., "aiw-3")
+    """
+    state = get_current_state(context_id, project_root)
+
+    if not state.tasks:
+        return "aiw-1"
+
+    # Find highest existing task number
+    max_num = 0
+    for task in state.tasks:
+        if task.id.startswith("aiw-"):
+            try:
+                num = int(task.id.split("-")[1])
+                max_num = max(max_num, num)
+            except (IndexError, ValueError):
+                pass
+
+    return f"aiw-{max_num + 1}"

package/dist/templates/_shared/lib/handoff/__init__.py

@@ -0,0 +1,22 @@
+"""Handoff utilities for context-aware session management.
+
+This module provides graceful context degradation when Claude's
+context window fills up. Instead of rushing or losing work,
+it creates a handoff document and facilitates clean session continuation.
+
+Components:
+- document_generator: Creates handoff documents with work state
+- context_monitor hook: Monitors context during tool use and triggers warnings
+"""
+
+from .document_generator import (
+    generate_handoff_document,
+    get_handoff_continuation_prompt,
+    HandoffDocument,
+)
+
+__all__ = [
+    "generate_handoff_document",
+    "get_handoff_continuation_prompt",
+    "HandoffDocument",
+]

package/dist/templates/_shared/lib/handoff/document_generator.py

@@ -0,0 +1,307 @@
+"""Handoff document generator for context-aware session management.
+
+Creates structured handoff documents when a session needs to transfer
+work to a new session (typically due to context window limits).
+
+Handoff documents capture:
+- Links to active plan and context folder
+- Current task state from events.jsonl
+- Work in progress summary
+- Next steps for continuation
+"""
+import json
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from ..base.atomic_write import atomic_write
+from ..base.constants import get_context_handoffs_dir, get_context_dir
+from ..base.utils import eprint, now_iso
+from ..context.event_log import (
+    append_event,
+    get_current_state,
+    get_pending_tasks,
+    Task,
+    EVENT_HANDOFF_CREATED,
+)
+from ..templates.formatters import render_task_list, format_continuation_header, format_reason
+
+
+@dataclass
+class HandoffDocument:
+    """Structured handoff document content."""
+    context_id: str
+    context_summary: str
+    session_id: str
+    reason: str  # e.g., "low_context", "user_requested", "error_recovery"
+    created_at: str
+
+    # Links
+    plan_path: Optional[str] = None
+    context_folder: str = ""
+    events_log_path: str = ""
+
+    # Task state
+    active_tasks: List[Dict[str, Any]] = field(default_factory=list)
+    completed_tasks_this_session: List[Dict[str, Any]] = field(default_factory=list)
+
+    # Context summary
+    work_summary: str = ""
+    next_steps: List[str] = field(default_factory=list)
+    important_notes: List[str] = field(default_factory=list)
+
+    # File path (set after saving)
+    file_path: Optional[str] = None
+
+
+def generate_handoff_document(
+    context_id: str,
+    reason: str = "low_context",
+    work_summary: str = "",
+    next_steps: Optional[List[str]] = None,
+    important_notes: Optional[List[str]] = None,
+    completed_this_session: Optional[List[str]] = None,
+    project_root: Path = None
+) -> Optional[HandoffDocument]:
+    """
+    Generate and save a handoff document for a context.
+
+    This creates a markdown document capturing current work state,
+    saves it to the context's handoffs folder, and records the event.
+
+    Args:
+        context_id: Context identifier
+        reason: Why handoff is happening (low_context, user_requested, etc.)
+        work_summary: Summary of current work in progress
+        next_steps: List of next steps for continuation
+        important_notes: Important decisions or context to preserve
+        completed_this_session: List of task subjects completed this session
+        project_root: Project root directory
+
+    Returns:
+        HandoffDocument with file_path set, or None on failure
+    """
+    from ..context.context_manager import get_context, update_handoff_status
+
+    context = get_context(context_id, project_root)
+    if not context:
+        eprint(f"[handoff] ERROR: Context '{context_id}' not found")
+        return None
+
+    # Generate session ID
+    session_id = str(uuid.uuid4())[:8]
+
+    # Get current state
+    state = get_current_state(context_id, project_root)
+    pending_tasks = get_pending_tasks(context_id, project_root)
+
+    # Build document
+    now = now_iso()
+    context_dir = get_context_dir(context_id, project_root)
+
+    doc = HandoffDocument(
+        context_id=context_id,
+        context_summary=context.summary,
+        session_id=session_id,
+        reason=reason,
+        created_at=now,
+        plan_path=context.in_flight.artifact_path if context.in_flight else None,
+        context_folder=str(context_dir),
+        events_log_path=str(context_dir / "events.jsonl"),
+        active_tasks=[_task_to_dict(t) for t in pending_tasks],
+        completed_tasks_this_session=[
+            {"subject": s} for s in (completed_this_session or [])
+        ],
+        work_summary=work_summary,
+        next_steps=next_steps or [],
+        important_notes=important_notes or [],
+    )
+
+    # Compute file path BEFORE rendering markdown
+    handoffs_dir = get_context_handoffs_dir(context_id, project_root)
+    handoffs_dir.mkdir(parents=True, exist_ok=True)
+
+    # Filename: YYYY-MM-DD-session-{session_id}.md
+    date_str = datetime.now().strftime("%Y-%m-%d")
+    filename = f"{date_str}-session-{session_id}.md"
+    file_path = handoffs_dir / filename
+
+    # Set file_path on doc BEFORE rendering markdown
+    doc.file_path = str(file_path)
+
+    # Generate markdown content
+    markdown = _render_handoff_markdown(doc)
+
+    # Save to handoffs folder
+
+    success, error = atomic_write(file_path, markdown)
+    if not success:
+        eprint(f"[handoff] ERROR: Failed to write handoff document: {error}")
+        return None
+
+    # Record event
+    append_event(
+        context_id,
+        EVENT_HANDOFF_CREATED,
+        project_root,
+        path=str(file_path),
+        reason=reason,
+        session_id=session_id
+    )
+
+    # Update context in_flight state
+    update_handoff_status(context_id, str(file_path), project_root)
+
+    eprint(f"[handoff] Created handoff document: {file_path}")
+    return doc
+
+
+def _task_to_dict(task: Task) -> Dict[str, Any]:
+    """Convert Task to dictionary for handoff document."""
+    return {
+        "id": task.id,
+        "subject": task.subject,
+        "status": task.status,
+        "description": task.description,
+    }
+
+
+def _render_handoff_markdown(doc: HandoffDocument) -> str:
+    """Render handoff document as markdown."""
+    lines = [
+        format_continuation_header("handoff", doc.context_id),
+        "",
+        f"**Created**: {doc.created_at}",
+        f"**Context ID**: {doc.context_id}",
+        f"**Session ID**: {doc.session_id}",
+        f"**Reason**: {format_reason(doc.reason)}",
+        "",
+        "## Links",
+        "",
+    ]
+
+    # Plan link
+    if doc.plan_path:
+        lines.append(f"- **Plan**: [{Path(doc.plan_path).name}]({doc.plan_path})")
+
+    lines.extend([
+        f"- **Context Folder**: `{doc.context_folder}`",
+        f"- **Events Log**: `{doc.events_log_path}`",
+        "",
+        "## Current State",
+        "",
+    ])
+
+    # Active tasks
+    lines.append(render_task_list(doc.active_tasks, header="Active Tasks", show_description=True).rstrip())
+    lines.append("")
+
+    # Completed this session
+    if doc.completed_tasks_this_session:
+        lines.append(render_task_list(
+            doc.completed_tasks_this_session,
+            header="Completed This Session",
+            show_description=False
+        ).rstrip())
+        lines.append("")
+
+    # Work summary
+    if doc.work_summary:
+        lines.extend([
+            "## Context Summary",
+            "",
+            doc.work_summary,
+            "",
+        ])
+
+    # Next steps
+    if doc.next_steps:
+        lines.extend([
+            "## Next Steps",
+            "",
+        ])
+        for i, step in enumerate(doc.next_steps, 1):
+            lines.append(f"{i}. {step}")
+        lines.append("")
+
+    # Important notes
+    if doc.important_notes:
+        lines.extend([
+            "## Important Notes",
+            "",
+        ])
+        for note in doc.important_notes:
+            lines.append(f"- {note}")
+        lines.append("")
+
+    # Continuation prompt
+    lines.extend([
+        "---",
+        "",
+        "**Continuation Prompt**:",
+        "```",
+        f'Continue working on context "{doc.context_id}".',
+        "",
+        f"Handoff document: {doc.file_path or 'See above'}",
+        "",
+        "Read the handoff document, restore tasks with TaskCreate, and continue implementation.",
+        "```",
+    ])
+
+    return "\n".join(lines)
+
+
+def get_handoff_continuation_prompt(doc: HandoffDocument) -> str:
+    """
+    Generate the prompt to paste into new session for continuation.
+
+    Args:
+        doc: HandoffDocument with file_path set
+
+    Returns:
+        Prompt string for continuing work
+    """
+    return f"""Continue working on context "{doc.context_id}".
+
+Handoff document: {doc.file_path}
+
+Read the handoff document, restore tasks with TaskCreate, and continue implementation."""
+
+
+def get_low_context_warning(context_remaining_percent: int, context_id: str) -> str:
+    """
+    Generate system reminder for low context warning.
+
+    This is injected by the UserPromptSubmit hook when context is low.
+
+    Args:
+        context_remaining_percent: Percentage of context remaining
+        context_id: Current context identifier
+
+    Returns:
+        System reminder markdown
+    """
+    return f"""<system-reminder>
+## LOW CONTEXT WARNING ({context_remaining_percent}% remaining)
+
+Your context window is running low. Please:
+
+1. **Finish current task** if 1-2 steps away, OR save current progress
+2. **Create handoff document** by calling:
+   ```python
+   from _shared.lib.handoff import generate_handoff_document
+   doc = generate_handoff_document(
+       context_id="{context_id}",
+       reason="low_context",
+       work_summary="<describe current work>",
+       next_steps=["<step 1>", "<step 2>"],
+       important_notes=["<key decision 1>"]
+   )
+   ```
+3. **Ask permission** to clear and paste continuation prompt
+
+After creating handoff, ask the user:
+"Context is low. I've created a handoff document. May I clear and continue in a new session?"
+</system-reminder>"""