@laitszkin/apollo-toolkit 2.0.0

package/improve-observability/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: improve-observability
+description: Add focused observability to an existing system so opaque workflows become diagnosable. Use when users ask to improve observability, add instrumentation, expand logs/metrics/traces, expose failure reasons, or make a business flow easier to debug without changing the product behavior itself.
+---
+
+# Improve Observability
+
+## Dependencies
+
+- Required: none.
+- Conditional: none.
+- Optional: none.
+- Fallback: not applicable.
+
+## Standards
+
+- Evidence: Read the real execution path and current telemetry before deciding where visibility actually disappears.
+- Execution: Add the smallest useful instrumentation around decision points, scope contracts, outcomes, and failure reasons.
+- Quality: Keep changes behavior-neutral, use structured high-signal telemetry, avoid secrets, and lock the signals with tests.
+- Output: Report which stages are now observable, which fields or metrics to inspect, and which tests validate the instrumentation.
+
+## Overview
+
+Use this skill to make a hard-to-debug path observable with minimal, evidence-driven changes. Prefer small, high-signal instrumentation around decision points, inputs, outcomes, and failure reasons rather than broad logging spam.
+
+## When To Use
+
+Use this skill when the user asks to:
+
+- add observability to an existing feature or service
+- expose why a workflow fails, stalls, retries, or exits early
+- enrich logs around a specific bug, incident, queue job, API call, or state transition
+- add metrics, traces, or structured fields so operators can isolate root cause faster
+- improve debugging without redesigning the whole subsystem
+
+Do not use this skill for generic bug fixing when the main request is behavior change rather than instrumentation.
+
+## Workflow
+
+### 1. Trace the real execution path
+
+- Read the relevant entrypoints, orchestration layers, and current telemetry before editing.
+- Identify the exact stages where information disappears: validation, branching, external calls, persistence, retries, settlement, cleanup, or error handling.
+- Reuse the project's existing logger, tracing library, metric naming style, and error taxonomy.
+
+### 2. Choose the smallest useful signals
+
+Add instrumentation only where it helps answer a concrete debugging question. Prefer:
+
+- stable request or job identifiers for cross-log correlation
+- structured fields for branch conditions, entity ids, counts, amounts, status, and reason codes
+- start/end markers for long multi-step flows
+- explicit logs for skipped paths and early returns
+- metrics or counters for outcome classes when aggregates matter
+- trace spans only when the project already uses tracing or timing data is necessary
+
+Avoid logging secrets, full payload dumps, or highly volatile text that breaks searchability.
+
+### 3. Instrument decision points, not just failures
+
+For each critical stage, make these states observable when relevant:
+
+- entered the stage
+- key preconditions or derived scope
+- branch selected
+- external dependency result
+- persisted side effect or emitted command
+- final outcome and failure reason
+
+If a failure is already logged, improve its context instead of duplicating another generic error line.
+
+### 3.1 Preserve cross-stage scope contracts
+
+When a workflow derives scope in one stage and consumes it later, make that contract observable end-to-end.
+
+- log the derived scope close to where it is computed
+- carry the same identifiers into downstream stages so operators can diff them directly
+- add explicit `missing_*` and `extra_*` fields when one stage should be a superset or exact match of another
+- prefer fail-fast diagnostics when a scope mismatch makes downstream errors ambiguous
+
+This is especially useful for pipelines such as discover -> precheck -> execution, where the real bug is often "stage B saw a different dependency set than stage A prepared".
+
+### 4. Keep changes behavior-neutral
+
+- Do not silently change business logic while adding observability.
+- If a tiny safety fix is required to support the instrumentation, isolate it and explain why.
+- Prefer additive fields over renamed fields unless the old format is actively harmful.
+
+### 5. Lock the signals with tests
+
+Add or update tests that prove the new observability survives refactors. Focus on:
+
+- emitted log fields or reason codes for the important branches
+- metrics increments for success, skip, and failure paths
+- regression coverage for the exact opaque scenario that motivated the work
+- edge paths such as early-return, dependency failure, and partial completion
+
+Use existing test helpers for log capture and avoid brittle assertions on timestamps or fully formatted log strings.
+
+## Output Expectations
+
+When finishing the task:
+
+- explain which stages are now observable
+- point to the key log fields, metrics, or spans that operators should inspect
+- mention any still-blind areas if they remain outside scope
+- run the most relevant tests for the touched instrumentation
+
+## Guardrails
+
+- Prefer structured, searchable telemetry over prose-heavy logs.
+- Minimize volume; high-signal beats high-noise.
+- Never add secrets, tokens, credentials, or raw personal data to telemetry.
+- Match existing naming conventions so dashboards and log queries stay coherent.

package/improve-observability/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Improve observability"
+  short_description: "Add targeted observability to debug hard-to-explain code paths."
+  default_prompt: "Use $improve-observability to add focused logs, traces, metrics, and tests around a failing or opaque workflow so the root cause becomes observable without changing product behavior."

package/learn-skill-from-conversations/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [v0.1.0] - 2026-02-17
+
+### Added
+- Added edge-case tests for extractor limit handling and latest-session selection.
+
+### Changed
+- Changed extractor default behavior to return all sessions in the last hour when `--limit` is omitted.
+- Updated documentation and skill instructions to remove the fixed `--limit 10` usage.
+- Kept `--limit` as an optional override for explicitly bounded extraction.

package/learn-skill-from-conversations/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Yamiyorunoshura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/learn-skill-from-conversations/README.md

@@ -0,0 +1,47 @@
+# learn-skill-from-conversations
+
+Learn and evolve your local Codex skill library from recent conversation logs.
+
+This skill extracts the latest conversations from `~/.codex/sessions` and `~/.codex/archived_sessions`, identifies reusable lessons, and applies skill updates through `skill-creator`.
+
+## Highlights
+
+- Reads all sessions from the last 24 hours
+- Stops immediately when there are no recent sessions
+- Cleans up `sessions` files older than 7 days after reading
+- Deletes `archived_sessions` files after reading them
+- Defaults to creating a new skill unless strong overlap is confirmed
+- Validates each changed skill with `quick_validate.py`
+
+## Project Structure
+
+```text
+.
+├── SKILL.md
+├── agents/
+│   └── openai.yaml
+└── scripts/
+    └── extract_recent_conversations.py
+```
+
+## Requirements
+
+- Python 3.9+
+- Access to `~/.codex/sessions`
+- Access to `~/.codex/archived_sessions`
+- Local `skill-creator` skill at `~/.codex/skills/.system/skill-creator`
+
+## Quick Start
+
+Run the extractor:
+
+```bash
+python3 scripts/extract_recent_conversations.py --lookback-minutes 1440
+```
+
+- If output is `NO_RECENT_CONVERSATIONS`, no action is required.
+- Otherwise, review extracted `[USER]` / `[ASSISTANT]` messages and apply updates through `skill-creator`.
+
+## License
+
+MIT. See `LICENSE` for details.

package/learn-skill-from-conversations/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: learn-skill-from-conversations
+description: Learn and evolve the local skill library from recent Codex conversation logs. Use when users ask to learn from past chats, mine ~/.codex/sessions or ~/.codex/archived_sessions, or automatically create/update skills from recurring lessons. The workflow reads all sessions from the last 24 hours, exits immediately if none exist, cleans up stale session files after reading, and applies skill changes through skill-creator with a default bias toward creating new skills.
+---
+
+# Learn Skill from Conversations
+
+## Dependencies
+
+- Required: `skill-creator` for all skill creation or update work.
+- Conditional: none.
+- Optional: none.
+- Fallback: If skill changes cannot be delegated through `skill-creator`, stop and report the blocked dependency.
+
+## Standards
+
+- Evidence: Extract recent Codex session history first and derive reusable lessons only from actual conversation patterns.
+- Execution: Prefer creating a new skill unless the overlap with an existing skill is clearly strong, then apply the change through `skill-creator`.
+- Quality: Take no action when there are no recent sessions, avoid unrelated broad refactors, and validate every changed skill.
+- Output: Report the analyzed sessions, extracted lessons, created or updated skills, and the reasoning behind each decision.
+
+## Overview
+
+Extract recent conversations, identify reusable lessons, and convert those lessons into concrete skill updates.
+
+## Required Resources
+
+- `scripts/extract_recent_conversations.py` for deterministic session extraction.
+- `$skill-creator` for all skill creation/update work.
+
+## Workflow
+
+### 1) Extract the latest conversation history
+
+- Run:
+
+```bash
+python3 ~/.codex/skills/learn-skill-from-conversations/scripts/extract_recent_conversations.py --lookback-minutes 1440
+```
+
+- If output is exactly `NO_RECENT_CONVERSATIONS`, stop immediately and report that no action is required.
+- Otherwise, review all `[USER]` and `[ASSISTANT]` blocks from each returned session.
+- The extractor reads both `~/.codex/sessions` and `~/.codex/archived_sessions`.
+- After extraction completes, it deletes `~/.codex/sessions` records older than 7 days and deletes all files under `~/.codex/archived_sessions`.
+
+### 2) Derive reusable lessons
+
+- Identify repeated user needs, recurring friction, and repeated manual workflows.
+- Ignore one-off issues that do not provide reusable value.
+
+### 3) Decide new skill vs existing skill (default: new skill)
+
+- Prefer creating a new skill.
+- Edit an existing skill only when the lesson is strongly related.
+- Treat relation as strong only when all three conditions hold:
+  - Same primary trigger intent.
+  - At least 70% workflow overlap.
+  - The update does not dilute the existing skill's scope.
+- If uncertain, create a new skill instead of expanding an old one.
+
+### 4) Apply changes through skill-creator
+
+- Explicitly follow `$skill-creator` workflow before editing skills.
+- For new skills, initialize with `~/.codex/skills/.system/skill-creator/scripts/init_skill.py`, then complete `SKILL.md` and required resources.
+- For existing skills, make minimal focused edits and keep behavior consistent.
+
+### 5) Validate every changed skill
+
+- Run:
+
+```bash
+python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py <skill-path>
+```
+
+- Resolve validation failures before finishing.
+
+### 6) Report result
+
+- Summarize analyzed sessions, extracted lessons, created/updated skills, and why each decision was made.
+
+## Guardrails
+
+- Take no action when there are no sessions in the last 24 hours.
+- Avoid broad refactors across unrelated skills.
+- Avoid duplicate skills when an existing skill is strongly related.

package/learn-skill-from-conversations/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Learn Skill from Conversations"
+  short_description: "Learn and evolve skills from recent chats"
+  default_prompt: "Use $learn-skill-from-conversations to review the last 24 hours of sessions, including archived sessions, and evolve skills."

package/learn-skill-from-conversations/scripts/extract_recent_conversations.py

@@ -0,0 +1,369 @@
+#!/usr/bin/env python3
+"""Extract recent Codex conversation history from Codex session stores."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Iterable, List, Optional, Sequence, Tuple
+
+DEFAULT_LOOKBACK_MINUTES = 24 * 60
+DEFAULT_RETENTION_DAYS = 7
+
+
+@dataclass
+class SessionRecord:
+    path: Path
+    timestamp_utc: datetime
+    messages: Optional[List[Tuple[str, str]]] = None
+
+
+def parse_iso_timestamp(raw: Optional[str]) -> Optional[datetime]:
+    if not raw:
+        return None
+    value = raw.strip()
+    if not value:
+        return None
+    if value.endswith("Z"):
+        value = value[:-1] + "+00:00"
+    try:
+        parsed = datetime.fromisoformat(value)
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)
+
+
+def read_session_timestamp(path: Path) -> Optional[datetime]:
+    try:
+        with path.open("r", encoding="utf-8") as handle:
+            first_line = handle.readline().strip()
+    except OSError:
+        return None
+
+    if not first_line:
+        return None
+
+    try:
+        first_entry = json.loads(first_line)
+    except json.JSONDecodeError:
+        return None
+
+    if first_entry.get("type") != "session_meta":
+        return None
+
+    payload = first_entry.get("payload", {})
+    if not isinstance(payload, dict):
+        return None
+
+    return parse_iso_timestamp(payload.get("timestamp")) or parse_iso_timestamp(first_entry.get("timestamp"))
+
+
+def iter_session_paths(root: Path) -> Iterable[Path]:
+    if not root.exists() or not root.is_dir():
+        return
+    yield from root.rglob("*.jsonl")
+
+
+def find_recent_sessions(
+    session_roots: Sequence[Path],
+    cutoff_utc: datetime,
+    limit: Optional[int],
+) -> List[SessionRecord]:
+    candidates: List[SessionRecord] = []
+    seen_paths = set()
+
+    for root in session_roots:
+        for path in iter_session_paths(root):
+            resolved_path = path.resolve()
+            if resolved_path in seen_paths:
+                continue
+            seen_paths.add(resolved_path)
+
+            timestamp_utc = read_session_timestamp(path)
+            if timestamp_utc is None:
+                continue
+            if timestamp_utc < cutoff_utc:
+                continue
+            candidates.append(SessionRecord(path=path, timestamp_utc=timestamp_utc))
+
+    candidates.sort(key=lambda record: record.timestamp_utc, reverse=True)
+    if limit is None:
+        return candidates
+    return candidates[:limit]
+
+
+def sanitize_text(text: str, max_chars: int) -> str:
+    cleaned = text.replace("\r\n", "\n").replace("\r", "\n").strip()
+    if max_chars <= 0:
+        return cleaned
+    if len(cleaned) <= max_chars:
+        return cleaned
+    return cleaned[: max_chars - 1].rstrip() + "..."
+
+
+def looks_like_wrapper_message(text: str) -> bool:
+    stripped = text.strip()
+    if not stripped:
+        return True
+    lower = stripped.lower()
+    return (
+        stripped.startswith("# AGENTS.md instructions for")
+        or stripped.startswith("<environment_context>")
+        or "<collaboration_mode>" in lower
+        or stripped.startswith("<permissions instructions>")
+        or stripped.startswith("<app-context>")
+    )
+
+
+def extract_text_from_content(content: Sequence[object]) -> str:
+    texts: List[str] = []
+    for part in content:
+        if not isinstance(part, dict):
+            continue
+        part_type = part.get("type")
+        if part_type in {"input_text", "output_text", "text"}:
+            value = part.get("text", "")
+            if isinstance(value, str) and value.strip():
+                texts.append(value)
+    return "\n".join(texts).strip()
+
+
+def extract_messages_from_event_entries(entries: Iterable[dict], max_chars: int) -> List[Tuple[str, str]]:
+    messages: List[Tuple[str, str]] = []
+    for entry in entries:
+        if entry.get("type") != "event_msg":
+            continue
+        payload = entry.get("payload", {})
+        if not isinstance(payload, dict):
+            continue
+
+        payload_type = payload.get("type")
+        if payload_type == "user_message":
+            text = payload.get("message", "")
+            if isinstance(text, str) and text.strip():
+                messages.append(("user", sanitize_text(text, max_chars)))
+        elif payload_type == "agent_message":
+            text = payload.get("message", "")
+            if isinstance(text, str) and text.strip():
+                messages.append(("assistant", sanitize_text(text, max_chars)))
+    return messages
+
+
+def extract_messages_from_response_items(entries: Iterable[dict], max_chars: int) -> List[Tuple[str, str]]:
+    messages: List[Tuple[str, str]] = []
+    for entry in entries:
+        if entry.get("type") != "response_item":
+            continue
+        payload = entry.get("payload", {})
+        if not isinstance(payload, dict):
+            continue
+        if payload.get("type") != "message":
+            continue
+
+        role = payload.get("role")
+        if role not in {"user", "assistant"}:
+            continue
+
+        text = extract_text_from_content(payload.get("content", []))
+        if not text or looks_like_wrapper_message(text):
+            continue
+        messages.append((role, sanitize_text(text, max_chars)))
+    return messages
+
+
+def extract_session_messages(path: Path, max_chars: int) -> List[Tuple[str, str]]:
+    entries: List[dict] = []
+    try:
+        with path.open("r", encoding="utf-8") as handle:
+            for line in handle:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    entries.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+    except OSError:
+        return []
+
+    event_messages = extract_messages_from_event_entries(entries, max_chars)
+    if event_messages:
+        return event_messages
+    return extract_messages_from_response_items(entries, max_chars)
+
+
+def delete_matching_files(root: Path, predicate) -> int:
+    if not root.exists() or not root.is_dir():
+        return 0
+
+    deleted_count = 0
+    for path in root.rglob("*.jsonl"):
+        if not predicate(path):
+            continue
+        try:
+            path.unlink()
+        except OSError:
+            continue
+        deleted_count += 1
+    return deleted_count
+
+
+def path_is_same_or_nested(path: Path, root: Optional[Path]) -> bool:
+    if root is None:
+        return False
+    try:
+        path.resolve().relative_to(root.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def cleanup_session_history(
+    sessions_dir: Path,
+    archived_sessions_dir: Path,
+    retention_cutoff_utc: datetime,
+) -> Tuple[int, int]:
+    sessions_root = sessions_dir.resolve() if sessions_dir.exists() else None
+    removed_old_sessions = delete_matching_files(
+        sessions_dir,
+        lambda path: (
+            (timestamp := read_session_timestamp(path)) is not None
+            and timestamp < retention_cutoff_utc
+        ),
+    )
+    removed_archived_sessions = delete_matching_files(
+        archived_sessions_dir,
+        lambda path: not path_is_same_or_nested(path, sessions_root),
+    )
+    return removed_old_sessions, removed_archived_sessions
+
+
+def render_text_output(
+    records: Sequence[SessionRecord],
+    lookback_minutes: int,
+    max_message_chars: int,
+    removed_old_sessions: int,
+    removed_archived_sessions: int,
+) -> str:
+    if not records:
+        return "NO_RECENT_CONVERSATIONS"
+
+    lines: List[str] = [
+        f"RECENT_CONVERSATIONS_FOUND={len(records)}",
+        f"LOOKBACK_MINUTES={lookback_minutes}",
+        "ARCHIVED_SESSIONS_INCLUDED=true",
+        f"CLEANUP_REMOVED_OLD_SESSIONS={removed_old_sessions}",
+        f"CLEANUP_REMOVED_ARCHIVED_SESSIONS={removed_archived_sessions}",
+    ]
+
+    for index, record in enumerate(records, start=1):
+        lines.append(f"=== SESSION {index} ===")
+        lines.append(f"TIMESTAMP_UTC={record.timestamp_utc.isoformat()}")
+        lines.append(f"FILE={record.path}")
+
+        messages = record.messages
+        if messages is None:
+            messages = extract_session_messages(record.path, max_message_chars)
+        if not messages:
+            lines.append("MESSAGES=NONE")
+            continue
+
+        for role, message in messages:
+            tag = "USER" if role == "user" else "ASSISTANT"
+            lines.append(f"[{tag}]")
+            lines.append(message)
+            lines.append(f"[/{tag}]")
+
+    return "\n".join(lines)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Extract the latest conversation history from Codex session stores",
+    )
+    parser.add_argument(
+        "--sessions-dir",
+        default="~/.codex/sessions",
+        help="Path to the Codex sessions directory (default: ~/.codex/sessions)",
+    )
+    parser.add_argument(
+        "--archived-sessions-dir",
+        default="~/.codex/archived_sessions",
+        help="Path to archived Codex sessions (default: ~/.codex/archived_sessions)",
+    )
+    parser.add_argument(
+        "--lookback-minutes",
+        type=int,
+        default=DEFAULT_LOOKBACK_MINUTES,
+        help=f"How far back to look for sessions (default: {DEFAULT_LOOKBACK_MINUTES})",
+    )
+    parser.add_argument(
+        "--limit",
+        type=int,
+        default=None,
+        help="Maximum number of sessions to return (default: all within lookback window)",
+    )
+    parser.add_argument(
+        "--max-message-chars",
+        type=int,
+        default=1600,
+        help="Maximum characters per extracted message (default: 1600)",
+    )
+    parser.add_argument(
+        "--retention-days",
+        type=int,
+        default=DEFAULT_RETENTION_DAYS,
+        help=f"Delete sessions older than this many days after reading (default: {DEFAULT_RETENTION_DAYS})",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+
+    sessions_dir = Path(args.sessions_dir).expanduser().resolve()
+    archived_sessions_dir = Path(args.archived_sessions_dir).expanduser().resolve()
+    lookback_minutes = max(args.lookback_minutes, 1)
+    limit = args.limit if args.limit is not None and args.limit > 0 else None
+    max_message_chars = max(args.max_message_chars, 100)
+    retention_days = max(args.retention_days, 1)
+    now_utc = datetime.now(timezone.utc)
+
+    if (
+        (not sessions_dir.exists() or not sessions_dir.is_dir())
+        and (not archived_sessions_dir.exists() or not archived_sessions_dir.is_dir())
+    ):
+        print("NO_RECENT_CONVERSATIONS")
+        return 0
+
+    cutoff_utc = now_utc - timedelta(minutes=lookback_minutes)
+    recent_records = find_recent_sessions((sessions_dir, archived_sessions_dir), cutoff_utc, limit)
+    for record in recent_records:
+        record.messages = extract_session_messages(record.path, max_message_chars)
+
+    retention_cutoff_utc = now_utc - timedelta(days=retention_days)
+    removed_old_sessions, removed_archived_sessions = cleanup_session_history(
+        sessions_dir,
+        archived_sessions_dir,
+        retention_cutoff_utc,
+    )
+
+    print(
+        render_text_output(
+            recent_records,
+            lookback_minutes,
+            max_message_chars,
+            removed_old_sessions,
+            removed_archived_sessions,
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())