pi-harness-runtime 0.10.11 → 0.10.13

package/RFC/0106_KNOWLEDGE_GRAPH_PROVENANCE.md

@@ -0,0 +1,368 @@
+# RFC-0106 — Knowledge Graph and Provenance Projection
+
+> **Status:** proposed
+> **Author:** pi-harness-runtime
+> **Replaces:** N/A
+> **Superseded by:** N/A
+> **Depends on:** RFC-0105 (Knowledge Retrieval)
+
+---
+
+## Summary
+
+Extend TencentDB-Agent-Memory's Knowledge Service (8424) to index all `moocoding-skills/*/SKILL.md` files as OKF encyclopedia with typed nodes and edges, creating a navigable knowledge graph with provenance linking to `RFC/*` and `IMPLEMENTATION/*`.
+
+---
+
+## Knowledge Service API (Port 8424)
+
+Base URL: `http://{host}:8424/v3`
+
+### Wiki Documents
+
+```bash
+# Create/update document
+POST /v3/wiki/documents
+Headers:
+  x-tdai-user-key: {user_key}
+  x-tdai-service-id: {service_id}
+Body:
+{
+  "title": "Frappe Custom Field Lifecycle",
+  "content": "# Frappe Custom Field Lifecycle\n\n## When to Use\n...",
+  "tags": ["frappe", "custom-field"],
+  "team_id": "moocoding"
+}
+
+# Get document
+GET /v3/wiki/documents/{document_id}
+Headers: x-tdai-user-key, x-tdai-service-id
+
+# List documents
+GET /v3/wiki/documents?team_id={team_id}&limit=100
+Headers: x-tdai-user-key, x-tdai-service-id
+
+# Delete document
+DELETE /v3/wiki/documents/{document_id}
+Headers: x-tdai-user-key, x-tdai-service-id
+```
+
+### Knowledge Graph
+
+```bash
+# Sync nodes and edges
+POST /v3/knowledge/graph/sync
+Headers: x-tdai-user-key, x-tdai-service-id
+Body:
+{
+  "nodes": [
+    {
+      "id": "skill:frappe-custom-field-lifecycle",
+      "type": "skill",
+      "data": {
+        "title": "Frappe Custom Field Lifecycle",
+        "description": "...",
+        "tags": ["frappe", "custom-field"],
+        "source": "frappe-bench/.claude-plugins/moocoding-skills/skills/frappe-custom-field-lifecycle/SKILL.md"
+      }
+    },
+    {
+      "id": "rfc:RFC-0052",
+      "type": "rfc",
+      "data": {
+        "title": "RFC-0052 Skill Registry Fix",
+        "source": "RFC/0052_SKILL_REGISTRY_FIX.md"
+      }
+    }
+  ],
+  "edges": [
+    {
+      "from": "skill:frappe-custom-field-lifecycle",
+      "to": "rfc:RFC-0052",
+      "type": "implements"
+    }
+  ]
+}
+
+# Search graph
+POST /v3/knowledge/graph/search
+Headers: x-tdai-user-key, x-tdai-service-id
+Body:
+{
+  "query": "frappe custom field",
+  "limit": 10
+}
+
+# Query by relationship
+POST /v3/knowledge/graph/query
+Headers: x-tdai-user-key, x-tdai-service-id
+Body:
+{
+  "type": "implements",
+  "from": "skill:frappe-custom-field-lifecycle"
+}
+```
+
+---
+
+## Node Types
+
+```typescript
+type KnowledgeNodeType =
+  | 'skill'           // SKILL.md entry
+  | 'rfc'             // RFC document
+  | 'implementation'  // IMPLEMENTATION/* entry
+  | 'concept'         // Abstract concept
+  | 'api'             // API endpoint
+  | 'cli'             // CLI command
+  | 'pattern'         // Code pattern
+  | 'workflow';       // Workflow/SOP
+
+interface KnowledgeNode {
+  id: string;           // e.g., "skill:frappe-custom-field-lifecycle"
+  type: KnowledgeNodeType;
+  data: {
+    title: string;
+    description?: string;
+    tags: string[];
+    source?: string;     // File path
+    url?: string;        // RFC/IMPLEMENTATION URL
+  };
+}
+```
+
+---
+
+## Edge Types
+
+```typescript
+type KnowledgeEdgeType =
+  | 'implements'       // Skill implements RFC
+  | 'depends_on'       // Skill A depends on Skill B
+  | 'supersedes'       // New version replaces old
+  | 'related_to'      // General relationship
+  | 'authored_by'     // Author attribution
+  | 'documents'        // RFC/Impl documents a skill
+  | 'references';      // RFC references implementation
+
+interface KnowledgeEdge {
+  from: string;          // Node ID
+  to: string;           // Node ID
+  type: KnowledgeEdgeType;
+  metadata?: {
+    confidence?: number;  // 0-1
+    source?: string;      // How was this edge discovered
+  };
+}
+```
+
+---
+
+## Provenance Mapping
+
+```
+RFC-0105 (Distributed Knowledge Retrieval)
+        ↓ implements
+IMPLEMENTATION/RFC-0105/
+        ↓ contains
+packages/tencentdb-memory/
+        ↓ indexes
+moocoding-skills/skills/tencentdb-sync/SKILL.md
+
+Knowledge Graph:
+  skill:tencentdb-sync --implements--> rfc:RFC-0105
+  skill:tencentdb-sync --documents--> implementation:RFC-0105
+```
+
+---
+
+## SKILL.md OKF Structure
+
+```markdown
+---
+id: frappe-custom-field-lifecycle
+type: skill
+title: Frappe Custom Field Lifecycle
+tags: [frappe, custom-field, database, migration]
+version: 1.0.0
+provenance:
+  implements: RFC-0052
+  related_implementation: IMPLEMENTATION/RFC-0052
+  author: moocoding
+---
+
+# Frappe Custom Field Lifecycle
+
+## When to Use
+...
+
+## Procedure
+...
+
+## Pitfalls
+...
+
+## Related Skills
+- [[skill:frappe-doctype-field-order]]
+- [[skill:property-setter-pattern]]
+```
+
+---
+
+## Extraction Pipeline
+
+```typescript
+// Extract knowledge from SKILL.md files → Knowledge Graph
+async function extractKnowledgeGraph(sourcePath: string, config: TencentDBConfig) {
+  // 1. Parse all SKILL.md files
+  const docs = indexDirectory(sourcePath);
+  
+  // 2. Create nodes and edges
+  const nodes: KnowledgeNode[] = [];
+  const edges: KnowledgeEdge[] = [];
+  
+  for (const doc of docs) {
+    // Create skill node
+    nodes.push({
+      id: `skill:${doc.id}`,
+      type: 'skill',
+      data: {
+        title: doc.title,
+        description: doc.sections[0]?.content.slice(0, 200),
+        tags: doc.metadata.tags,
+        source: doc.metadata.source,
+      }
+    });
+    
+    // Extract provenance from frontmatter
+    const provenance = doc.metadata.provenance;
+    if (provenance.implements) {
+      edges.push({
+        from: `skill:${doc.id}`,
+        to: `rfc:${provenance.implements}`,
+        type: 'implements'
+      });
+    }
+    if (provenance.related_implementation) {
+      edges.push({
+        from: `skill:${doc.id}`,
+        to: `implementation:${provenance.related_implementation}`,
+        type: 'documents'
+      });
+    }
+    
+    // Link to RFCs found in content
+    const rfcRefs = extractRFCRefs(doc.content);
+    for (const rfc of rfcRefs) {
+      edges.push({
+        from: `skill:${doc.id}`,
+        to: `rfc:${rfc}`,
+        type: 'references'
+      });
+    }
+    
+    // Wiki links become edges
+    for (const link of doc.links) {
+      if (link.startsWith('skill:')) {
+        edges.push({
+          from: `skill:${doc.id}`,
+          to: link,
+          type: 'related_to'
+        });
+      }
+    }
+  }
+  
+  // 3. Sync to Knowledge Service
+  await syncGraph({
+    nodes,
+    edges,
+    config
+  });
+}
+
+// Sync to Knowledge Service (8424)
+async function syncGraph(payload: { nodes: KnowledgeNode[], edges: KnowledgeEdge[] }, config: TencentDBConfig) {
+  const response = await fetch(`${config.knowledgeUrl}/v3/knowledge/graph/sync`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-tdai-user-key': config.userKey,
+      'x-tdai-service-id': config.serviceId,
+    },
+    body: JSON.stringify(payload)
+  });
+  return response.json();
+}
+```
+
+---
+
+## MCP Integration (RFC-0106)
+
+```typescript
+interface KnowledgeGraphMCP {
+  // Search skills via Knowledge Service
+  kg_search(query: string): Promise<SearchResult[]>;
+  
+  // Query graph relationships
+  kg_query(type: string, from?: string, to?: string): Promise<Edge[]>;
+  
+  // Get node details
+  kg_node(id: string): Promise<KnowledgeNode>;
+  
+  // Get skill by RFC
+  kg_findByRFC(rfcId: string): Promise<KnowledgeNode[]>;
+  
+  // Get related skills
+  kg_related(skillId: string): Promise<KnowledgeNode[]>;
+}
+```
+
+---
+
+## File Structure
+
+```
+packages/tencentdb-memory/
+├── src/
+│   ├── client.ts          # Memory Core client (8420)
+│   ├── knowledge.ts        # Knowledge Service client (8424)
+│   ├── proxy.ts           # Proxy client (8096)
+│   ├── loader.ts         # SKILL.md loader
+│   ├── indexer.ts        # OKF indexer (from okf-indexer package)
+│   └── sync.ts           # Graph sync pipeline
+└── package.json
+
+packages/okf-indexer/
+├── src/
+│   ├── indexer.ts        # Parse SKILL.md → OKF
+│   ├── extractor.ts      # Extract provenance/edges
+│   └── cli.ts           # CLI for indexing
+└── package.json
+
+scripts/
+└── tencentdb-sync.ts    # Sync CLI
+```
+
+---
+
+## Dependencies
+
+| Dependency | Purpose |
+|------------|---------|
+| TencentDB-Agent-Memory | Knowledge Service (8424) |
+| okf-indexer | SKILL.md → OKF parsing |
+| chokidar | File watching for auto-sync |
+
+---
+
+## Files
+
+See `IMPLEMENTATION/RFC-0106/FILES.md`.
+
+---
+
+## Acceptance Criteria
+
+See `IMPLEMENTATION/RFC-0106/ACCEPTANCE_CRITERIA.md`.

package/RFC/README.md

@@ -0,0 +1,11 @@
+# Day 2 RFC Plan
+
+This folder will contain initial RFC documents.
+
+Planned files:
+
+- `0001_LOOP_RUNTIME.md`
+- `0002_PROVIDER_ADAPTER.md`
+- `0003_QUOTA_MANAGER.md`
+- `0004_PLAYWRIGHT_ADAPTER.md`
+- `0005_GIT_WORKTREE.md`

package/cli.ts

@@ -0,0 +1,111 @@
+/**
+ * Pure helper functions — testable without pi context.
+ * Imported by tracker.ts, mirror.ts, windows.ts, renderer.ts.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+
+/** Resolve the ~/.pi/usage-status/ directory. Override with PI_USAGE_DIR env var (testing). */
+export function getUsageDir(): string {
+	const override = process.env.PI_USAGE_DIR;
+	if (override) return override;
+	return join(homedir(), ".pi", "usage-status");
+}
+
+/** Resolve the JSONL usage log path. */
+export function getUsageLogPath(): string {
+	return join(getUsageDir(), "usage.jsonl");
+}
+
+/** Resolve the mirror JSON path. */
+export function getMirrorPath(): string {
+	return join(getUsageDir(), "mirror.json");
+}
+
+/** Ensure the directory exists. Idempotent. */
+export function ensureUsageDir(): void {
+	const dir = getUsageDir();
+	if (!existsSync(dir)) {
+		mkdirSync(dir, { recursive: true });
+	}
+}
+
+/** Read the JSONL usage log as an array of UsageRecord. Returns [] if missing. */
+export function readJsonl<T>(path: string): T[] {
+	if (!existsSync(path)) return [];
+	const text = readFileSync(path, "utf-8");
+	const out: T[] = [];
+	for (const line of text.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		try {
+			out.push(JSON.parse(trimmed) as T);
+		} catch {
+			// skip corrupted line
+		}
+	}
+	return out;
+}
+
+/** Append a single JSON line to a JSONL file. */
+export function appendJsonl(path: string, record: unknown): void {
+	ensureUsageDir();
+	const line = JSON.stringify(record) + "\n";
+	appendFileSync(path, line, "utf-8");
+}
+
+/** Read JSON file safely. Returns null if missing or corrupted. */
+export function readJson(path: string): unknown | null {
+	if (!existsSync(path)) return null;
+	try {
+		return JSON.parse(readFileSync(path, "utf-8"));
+	} catch {
+		return null;
+	}
+}
+
+/** Write JSON file (creates parent dir if needed). */
+export function writeJson(path: string, data: unknown): void {
+	ensureUsageDir();
+	if (!existsSync(dirname(path))) {
+		mkdirSync(dirname(path), { recursive: true });
+	}
+	writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+
+/** Format milliseconds as "Xh Ym" or "Xd Yh" or "Xm" or "Xs". */
+export function formatDuration(ms: number): string {
+	const abs = Math.max(0, Math.floor(ms / 1000));
+	const sec = abs % 60;
+	const min = Math.floor(abs / 60) % 60;
+	const hr = Math.floor(abs / 3600) % 24;
+	const day = Math.floor(abs / 86400);
+	if (day > 0) return `${day}d ${hr}h`;
+	if (hr > 0) return `${hr}h ${min}m`;
+	if (min > 0) return `${min}m`;
+	return `${sec}s`;
+}
+
+/** Format a timestamp as relative time "X min ago". */
+export function formatRelative(fromIso: string, nowMs: number): string {
+	const fromMs = Date.parse(fromIso);
+	if (isNaN(fromMs)) return "unknown";
+	const deltaMs = nowMs - fromMs;
+	return formatDuration(deltaMs) + " ago";
+}
+
+/** Format a token count with k/M suffix. */
+export function formatTokens(n: number): string {
+	if (n < 1000) return String(n);
+	if (n < 1_000_000) return `${(n / 1000).toFixed(1)}k`;
+	return `${(n / 1_000_000).toFixed(2)}M`;
+}
+
+/** Format USD cost with 2-4 decimals depending on size. */
+export function formatUsd(n: number): string {
+	if (n < 0.01) return `$${n.toFixed(4)}`;
+	if (n < 100) return `$${n.toFixed(2)}`;
+	return `$${n.toFixed(0)}`;
+}

package/footer-status.ts

@@ -0,0 +1,204 @@
+import type { MirrorRecord, ProviderMirrorRecord } from "./mirror.ts";
+
+import {
+	parseContextWindowStatusLine,
+	parseQuotaUsageStatusLine,
+	type ParsedContextWindowUsage,
+	type ParsedQuotaUsageData,
+} from "./status-parsers.ts";
+import { getProviderLabel } from "./packages/types/src/ai-providers.js";
+import {
+	providerHasContinuousScrape,
+	providerHasTUISignal,
+} from "./packages/providers/src/provider-id.js";
+
+export type ParsedFooterStatusValue =
+	| { kind: "quota"; value: ParsedQuotaUsageData }
+	| { kind: "context-window"; value: ParsedContextWindowUsage }
+	| { kind: "today"; value: { tokens: number; cost: number } }
+	| { kind: "unknown"; value: null };
+
+export function parseFooterStatusValue(value: string): ParsedFooterStatusValue {
+	const quota = parseQuotaUsageStatusLine(value);
+	if (quota) {
+		return { kind: "quota", value: quota };
+	}
+
+	const contextWindow = parseContextWindowStatusLine(value);
+	if (contextWindow) {
+		return { kind: "context-window", value: contextWindow };
+	}
+
+	const todayMatch = value.match(/^today:\s*([\d,.]+)k tok\s*·\s*\$([\d,.]+)/i);
+	if (todayMatch) {
+		const tokens = Number.parseFloat(todayMatch[1].replace(/,/g, "")) * 1000;
+		const cost = Number.parseFloat(todayMatch[2].replace(/,/g, ""));
+		if (Number.isFinite(tokens) && Number.isFinite(cost)) {
+			return {
+				kind: "today",
+				value: { tokens, cost },
+			};
+		}
+	}
+
+	return { kind: "unknown", value: null };
+}
+
+/**
+ * Get display label for a provider id.
+ * Uses the canonical getProviderLabel() from packages/types/src/ai-providers.ts
+ * which handles all 9 known providers: minimax, openai, anthropic, glm,
+ * openrouter, openai-codex, deepseek, gemini, kimi.
+ */
+function providerDisplayName(provider: string | null | undefined): string {
+	if (!provider) return "Provider";
+	return getProviderLabel(provider);
+}
+
+/**
+ * Hint shown when the provider has no usage data yet.
+ * Covers all 9 known providers from KNOWN_AI_PROVIDERS.
+ */
+function missingDataHint(
+	provider: string | null | undefined,
+	hasCookieSource: boolean,
+): string {
+	if (!provider) return "no usage source configured";
+
+	// MiniMax: needs cookies for continuous scrape
+	if (provider === "minimax") {
+		return hasCookieSource
+			? "no data yet (updates after first scrape)"
+			: "drop minimax cookies into ~/.pi-harness-runtime/cookies/";
+	}
+
+	// TUI signal providers: one-shot signal on limit hit
+	if (providerHasTUISignal(provider)) {
+		return "no signal yet (updates on first limit hit)";
+	}
+
+	// Providers without any tracking implementation yet
+	// deepseek, gemini, kimi, or any unknown provider
+	if (provider === "deepseek") {
+		return "deepseek usage tracking not yet implemented";
+	}
+	if (provider === "gemini") {
+		return "gemini usage tracking not yet implemented";
+	}
+	if (provider === "kimi") {
+		return "kimi usage tracking not yet implemented";
+	}
+
+	// Generic fallback for any other unknown provider
+	if (!hasCookieSource) return "no usage source configured";
+	return "no data yet";
+}
+
+/** Normalize an unknown mirror record into a ProviderMirrorRecord view. */
+function toProviderView(
+	mirror: MirrorRecord | ProviderMirrorRecord | null,
+): ProviderMirrorRecord | null {
+	if (!mirror) return null;
+	const m = mirror as ProviderMirrorRecord;
+	if (typeof m.provider === "string") return m;
+	// Legacy flat-shape: already a single record without a provider wrapper.
+	return {
+		synced_at: m.synced_at ?? new Date().toISOString(),
+		provider: (m as MirrorRecord).provider ?? "",
+		source: "scrape",
+		model: (m as MirrorRecord).model,
+		h5_used_pct: (m as MirrorRecord).h5_used_pct,
+		h5_resets_at: (m as MirrorRecord).h5_resets_at,
+		weekly_used_pct: (m as MirrorRecord).weekly_used_pct,
+		weekly_resets_at: (m as MirrorRecord).weekly_resets_at,
+	};
+}
+
+export function buildFooterStatusValue(
+	local: { today: { tokens: number; cost: number } },
+	mirror: MirrorRecord | ProviderMirrorRecord | null,
+	freshness: "fresh" | "stale" | "expired" | "missing",
+	hasCookieSource: boolean = true,
+	activeProvider: string | null = null,
+): string {
+	const view = toProviderView(mirror);
+	const provider = activeProvider ?? view?.provider ?? null;
+	const label = providerDisplayName(provider);
+
+	// TUI-signal exhaustion path: fires when limit is hit (one-shot signal).
+	// This takes priority over continuous data to show the most recent state.
+	if (
+		provider &&
+		view &&
+		view.exhausted &&
+		(view.limitType !== undefined ||
+			view.resets_at !== undefined ||
+			view.h5_resets_at !== undefined)
+	) {
+		const reset = view.resets_at ?? view.h5_resets_at ?? "soon";
+		const limitType = view.limitType ?? "tokens";
+		return `${label}: limit hit (${limitType}), reset ${reset}`;
+	}
+
+	// Continuous data path: providers with continuous scrape (MiniMax has 5h+weekly, OpenAI has weekly-only)
+	if (
+		provider &&
+		providerHasContinuousScrape(provider) &&
+		view &&
+		freshness !== "expired" &&
+		(view.h5_used_pct !== undefined || view.weekly_used_pct !== undefined)
+	) {
+		const weeklyPct = view.weekly_used_pct ?? 0;
+		const weeklyLeft = Math.max(0, 100 - weeklyPct);
+		const weeklyResets = view.weekly_resets_at ?? "soon";
+
+		let statusLine: string;
+		if (view.h5_used_pct !== undefined) {
+			// MiniMax: has both 5h and weekly windows
+			const h5Pct = view.h5_used_pct;
+			const h5Left = Math.max(0, 100 - h5Pct);
+			statusLine = `5h: ${h5Left.toFixed(0)}% left · week: ${weeklyLeft.toFixed(0)}% left`;
+		} else {
+			// OpenAI: weekly-only (no 5h window)
+			statusLine = `week: ${weeklyLeft.toFixed(0)}% left (resets ${weeklyResets})`;
+		}
+
+		const freshnessSuffix =
+			freshness === "fresh" || freshness === "missing" ? "" : ` · ${freshness}`;
+		return `${label}: ${statusLine}${freshnessSuffix}`;
+	}
+
+	// TUI signal providers (OpenAI, Anthropic, GLM, OpenRouter):
+	// Show monitoring status when we have a record but haven't hit limits.
+	// These providers only emit data when a limit is hit.
+	if (
+		provider &&
+		providerHasTUISignal(provider) &&
+		view &&
+		freshness !== "expired"
+	) {
+		// If exhausted is not set, we're monitoring normally
+		if (!view.exhausted) {
+			return `${label}: monitoring (no limits hit)`;
+		}
+	}
+
+	// Discoverable hint when we have no data yet.
+	if (
+		provider &&
+		(!view || freshness === "expired" || freshness === "missing")
+	) {
+		const hint = missingDataHint(provider, hasCookieSource);
+		// MiniMax-on-fresh-machine still gets the cookie hint; for others
+		// the hint explains the signal-driven design.
+		if (provider === "minimax" && !hasCookieSource) {
+			return `${label}: 5h: -- (${hint})`;
+		}
+		return `${label}: 5h: -- · week: -- (${hint})`;
+	}
+
+	// Silent fallback: only reached if we genuinely don't know the provider.
+	// No "5h/week: --" line here because we'd be making up data.
+	const todayStr = `${(local.today.tokens / 1000).toFixed(1)}k tok · $${local.today.cost.toFixed(3)}`;
+	return `today: ${todayStr}`;
+}