feat(cli): redesign CLI to wrap SDK with git-like commands - #1
Open
Emerald-dev0 wants to merge 18 commits into
Open
feat(cli): redesign CLI to wrap SDK with git-like commands#1Emerald-dev0 wants to merge 18 commits into
Emerald-dev0 wants to merge 18 commits into
Conversation
…and multi-tenant isolation - Store class with insert, supersede, archive, tombstone, DAG traversal - 45 tests covering store operations, DAG invariants, conflict detection - Deterministic ORDER BY with rowid tiebreaker for sub-second timestamp resolution - MEMORY.md with repository workflow rules - docs/DEVIATIONS.md with spec ambiguity resolutions
…flict detection, token budget, and caching The Compiler transforms the raw append-only log into the active context set agents receive. Five passes: scope resolution (inheritance across ancestor scopes), status filter, CID dedup with supersession resolution, inherentance (child overrides parent), and kind-ordered output. Key features: - Scope inheritance: child scopes inherit parent entries unless overridden - Conflict detection: duplicate cids within same scope with different messages and no supersession are flagged, both entries returned - Supersession resolution: superseded entries never leak into output - Token budget: compress observations first, then decisions; never drop rules silently; all drops logged with reason - Task relevance ranking: optional keyword-based relevance scoring - Caching: per (scope, budget, kind, cid), invalidated on scope change - Provenance: every compiled entry tracks sourceScope, inherited flag, fromParent, and supersedesChain - Graceful degradation: summarize before dropping, never silently drop high-confidence constraints 69 tests pass (26 store, 26 compiler, 17 DAG)
…agent integration test
Replaces the Supabase-backed v1 with a local-first MCP server built on
@contextly/protocol (Store + Compiler).
Five tools matching protocol primitives:
- read_context: compiled context via Context Compiler with budget, kind,
cid, and task-relevance options
- commit: idempotent entry creation with conflict detection
- query: raw SQLite lookup bypassing compilation (for tooling/debug)
- resolve: conflict resolution via supersession
- fork/merge: scope branching with inheritance
Auth handshake:
- Token format: ctx_{scope}_{base64url} — embeds scope for zero-DB auth
- verifyTokenIntegrity, validateScope, permission checks on every call
- Parent token grants access to child scopes, sibling scopes are isolated
Rate limiting:
- Per-operation sliding window (read: 100/min, write: 30/min, etc.)
- Resets after window expiry, structured RateLimitError with retryAfter
Structured errors:
- Machine-readable error codes (INVALID_TOKEN, SCOPE_MISMATCH, etc.)
- Agents can reason about errors programmatically, not just HTTP codes
Integration test (16 tests):
- Two-agent loop: Alice reads empty context, commits → Bob reads Alice's
context, commits his own → both see all entries
- Conflict detection: Alice and Bob write different messages for same cid
- Conflict resolution: Bob supersedes Alice's entry with a new decision
- Auth enforcement: scope mismatch rejects, parent-child scope allows
- Rate limiting: window enforcement and auto-reset
- Fork with inheritance: child scope inherits parent entries
- Idempotency: duplicate commit returns existing entry
…ion example - TypeScript SDK (packages/sdk/) — Contextly class wrapping MCP tools via in-memory transport; verbs: read, commit, query, resolve, fork, merge, onConflict - Python SDK (packages/sdk-py/) — subprocess-based MCP client with same API - Quickstart doc (docs/AGENT_SDK_QUICKSTART.md) — under-10-lines examples - Cross-session persistent-agent example (examples/persistent-agent/) — two scripts demonstrating context inheritance across agent sessions
…OC2 compliance export
… for cross-tenant access, conflict spikes, sync divergence
…d(), ancestryDag() for developer introspection
…cs, alerting, debug, exporter, and full lifecycle
- Add API server package with Express.js - Implement all 6 protocol primitives as REST endpoints: - POST /v1/read_context - read compiled context - POST /v1/commit - create context entries - POST /v1/query - query/filter entries - POST /v1/resolve - resolve conflicts - POST /v1/fork - fork scopes - POST /v1/merge - merge scopes - Add authentication middleware (API keys + JWT Bearer tokens) - Implement scope-based authorization with permissions - Add rate limiting (per-tenant and per-API-key) - Build webhook system with retries, idempotency, signed payloads - Auto-generate OpenAPI spec from implementation - Swagger UI at /docs - Postman collection included - Comprehensive test suite
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Redesigns the Contextly CLI to wrap the SDK instead of talking to the protocol directly, ensuring consistent behavior between code and terminal.
Changes
Core Commands
Authentication
Output Formatting
Design Principles
Files Added/Modified
Testing
Breaking Changes
Closes: CLI redesign (Prompt 12)