Skip to content

feat(session): add used() endpoint for context/skill tracking#684

Merged
zhoujh01 merged 1 commit intomainfrom
feat/session-used-endpoint
Mar 17, 2026
Merged

feat(session): add used() endpoint for context/skill tracking#684
zhoujh01 merged 1 commit intomainfrom
feat/session-used-endpoint

Conversation

@qin-ctx
Copy link
Copy Markdown
Collaborator

@qin-ctx qin-ctx commented Mar 17, 2026

Description

Add a new POST /api/v1/sessions/{session_id}/used endpoint that records actually used contexts and skills during a session. When commit() is called, active_count is updated based on this usage data. Also overhauls all plugin installation documentation with simplified flows, compatibility warnings, and expanded troubleshooting.

Related Issue

Type of Change

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update
  • Refactoring (no functional changes)
  • Performance improvement
  • Test update

Changes Made

  • Add POST /{session_id}/used API endpoint in sessions.py with UsedRequest model (accepts contexts and skill fields)
  • Add used() API documentation in both English and Chinese session docs
  • Update session workflow examples to include the new usage recording step
  • Overhaul README.md: restructure with table of contents, one-click installation, configuration reference, daily usage, web console, troubleshooting, and uninstallation sections
  • Overhaul INSTALL.md and INSTALL-ZH.md: simplify to npm global package, add curl one-click method, add OpenClaw >= 2026.3.12 compatibility warning, add Plugin 2.0 announcement, expand troubleshooting
  • Simplify INSTALL-AGENT.md: replace repo-clone workflow with npm global install

Testing

  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • I have tested this on the following platforms:
    • Linux
    • macOS
    • Windows

Checklist

  • My code follows the project's coding style
  • I have performed a self-review of my code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • Any dependent changes have been merged and published

Screenshots (if applicable)

N/A

Additional Notes

The used() endpoint is designed to be called between add-message() and commit() in the session lifecycle, allowing clients to report which loaded contexts and skills were actually consumed during the conversation turn.

🤖 Generated with Claude Code

@qin-ctx
feat(session): add used() endpoint and overhaul plugin install docs
24b27bd 
Add POST /sessions/{session_id}/used API to record actually used
contexts and skills, enabling active_count tracking on commit.
Overhaul all plugin installation docs: simplify to npm global install,
add OpenClaw >= 2026.3.12 compatibility warning, expand troubleshooting
and configuration reference.

Co-Authored-By: Claude Opus 4.6
@CLAassistant
Copy link
Copy Markdown

CLAassistant commented Mar 17, 2026 •
edited
Loading

CLA assistant check
All committers have signed the CLA.

@github-actions
Copy link
Copy Markdown

github-actions bot commented Mar 17, 2026

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪
🧪 No relevant tests
🔒 No security concerns identified
⚡ Recommended focus areas for review

Input Validation Missing

The UsedRequest model lacks validation: 1) At least one of contexts or skill should be provided. 2) If skill is provided, it should include required fields like uri and success (per documentation). 3) contexts should not be an empty list when provided. Add Pydantic validators to enforce these constraints.

 
class UsedRequest(BaseModel):
    """Request model for recording usage."""

    contexts: Optional[List[str]] = None
    skill: Optional[Dict[str, Any]] = None
Session Persistence Check

After calling session.used(), verify whether the session changes (e.g., stats.contexts_used, stats.skills_used) are persisted. If not, add a session.save() call or ensure persistence through another mechanism.

 
session = service.sessions.session(_ctx, session_id)
await session.load()
session.used(contexts=request.contexts, skill=request.skill)

@github-actions
Copy link
Copy Markdown

github-actions bot commented Mar 17, 2026

PR Code Suggestions ✨

Explore these optional code suggestions:

CategorySuggestion                                                                                                                                    Impact
Possible issue
Validate at least one field provided

Add validation to ensure at least one of contexts or skill is provided in the
request. This prevents calling the endpoint with no actionable data, which would be
a no-op.

openviking/server/routers/sessions.py [79-84]

 class UsedRequest(BaseModel):
     """Request model for recording usage."""
 
     contexts: Optional[List[str]] = None
     skill: Optional[Dict[str, Any]] = None
 
+    def validate_non_empty(self) -> "UsedRequest":
+        if self.contexts is None and self.skill is None:
+            raise ValueError("Either 'contexts' or 'skill' must be provided")
+        return self
+
Suggestion importance[1-10]: 5

__

Why: The suggestion adds a validation method to ensure at least one of contexts or skill is provided, preventing no-op calls to the endpoint. This improves the API's robustness.

Low
Enforce non-empty request validation

Call the validation method on UsedRequest to enforce that at least one of contexts
or skill is provided before processing the request.

openviking/server/routers/sessions.py [308-318]

 @router.post("/{session_id}/used")
 async def record_used(
     request: UsedRequest,
     session_id: str = Path(..., description="Session ID"),
     _ctx: RequestContext = Depends(get_request_context),
 ):
     """Record actually used contexts and skills in a session."""
+    request.validate_non_empty()
     service = get_service()
     session = service.sessions.session(_ctx, session_id)
     await session.load()
     session.used(contexts=request.contexts, skill=request.skill)
Suggestion importance[1-10]: 5

__

Why: The suggestion correctly calls the validation method (from the previous suggestion) in the endpoint, ensuring the validation is actually enforced before processing the request.

Low

@zhoujh01 zhoujh01 merged commit ded21cb into main Mar 17, 2026
5 of 6 checks passed
@zhoujh01 zhoujh01 deleted the feat/session-used-endpoint branch March 17, 2026 06:17
@github-project-automation github-project-automation bot moved this from Backlog to Done in OpenViking project Mar 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@zhoujh01 zhoujh01 zhoujh01 approved these changes

Assignees

No one assigned

Labels

Review effort 3/5

Projects

OpenViking project
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@qin-ctx @CLAassistant @zhoujh01