@shiyuhang0/ticloud-oncall 0.1.0

package/README.md

@@ -0,0 +1,52 @@
+# TiCloud Oncall Plugin
+
+这是一个接入 opencode 的本地 plugin 项目，用于内部 oncall 场景。
+
+当前版本提供：
+
+- `ticloud` 主协调 agent
+- `clinic_cluster_query` 集群元数据查询 tool
+- `loki_log_query` Loki 直连日志查询 tool
+- 复用 opencode 内置 `explore` subagent 做本地代码搜索
+
+代码搜索约束：
+
+- 当需要代码证据时，用户应提供 `REPO_ROOTS`
+- `explore` 只应搜索从 `REPO_ROOTS` 缩小出的候选 repo，不应盲搜整个 workspace
+
+## Setup
+
+1. 安装依赖：`npm install`
+2. 在 opencode plugin 参数里配置：`CLINIC_API_KEY`、`CLINIC_ENV`、`REPO_ROOTS`
+3. 构建：`npm run build`
+4. 在 opencode 配置中加载 `dist/src/index.js`
+
+日志查询规则摘要：
+
+- 只走 Loki 直连 API
+- 先 `labels`，再 `label_values`，最后 `query_range`
+- 先宽搜，再窄搜
+- 单次查询时间范围必须在 30 天内
+
+## opencode config
+
+```json
+{
+  "plugin": [["./dist/src/index.js", {
+    "CLINIC_API_KEY": "<your-clinic-api-key>",
+    "CLINIC_ENV": "prod", // optional,defauts to "prod"
+    "REPO_ROOTS": [
+      "/Users/you/github/tidb-cloud",
+      "/Users/you/github/platform-services"
+    ]
+  }]]
+}
+```
+
+## 文档
+
+- quickstart：`docs/guides/quickstart.md`
+- 架构与亮点：`docs/architecture/overview-and-highlights.md`
+- 设计说明：`docs/architecture/ticloud-oncall-plugin-design.md`
+- 实现计划：`docs/superpowers/plans/2026-06-03-ticloud-oncall-plugin.md`
+- 使用部署：`docs/guides/ticloud-oncall-plugin-usage.md`

package/dist/src/agents/log-analyzer.d.ts

@@ -0,0 +1,12 @@
+export declare const LogAnalyzerAgent: {
+    name: string;
+    mode: string;
+    description: string;
+    prompt: string;
+    permission: {
+        "*": string;
+        loki_log_query: string;
+        task: string;
+    };
+    options: {};
+};

package/dist/src/agents/log-analyzer.js

@@ -0,0 +1,13 @@
+import { LogAnalyzerPrompt } from "../prompts/log-analyzer.js";
+export const LogAnalyzerAgent = {
+    name: "log-analyzer",
+    mode: "subagent",
+    description: "Specialized worker for Clinic Loki log queries",
+    prompt: LogAnalyzerPrompt,
+    permission: {
+        "*": "deny",
+        loki_log_query: "allow",
+        task: "deny",
+    },
+    options: {},
+};

package/dist/src/agents/metadata-querier.d.ts

@@ -0,0 +1,12 @@
+export declare const MetadataQuerierAgent: {
+    name: string;
+    mode: string;
+    description: string;
+    prompt: string;
+    permission: {
+        "*": string;
+        clinic_cluster_query: string;
+        task: string;
+    };
+    options: {};
+};

package/dist/src/agents/metadata-querier.js

@@ -0,0 +1,13 @@
+import { MetadataQuerierPrompt } from "../prompts/metadata-querier.js";
+export const MetadataQuerierAgent = {
+    name: "metadata-querier",
+    mode: "subagent",
+    description: "Specialized worker for Clinic cluster metadata lookups",
+    prompt: MetadataQuerierPrompt,
+    permission: {
+        "*": "deny",
+        clinic_cluster_query: "allow",
+        task: "deny",
+    },
+    options: {},
+};

package/dist/src/agents/ticloud.d.ts

@@ -0,0 +1,13 @@
+export declare const TicloudAgent: {
+    name: string;
+    mode: string;
+    description: string;
+    prompt: string;
+    permission: {
+        task: string;
+        todowrite: string;
+        question: string;
+        loki_log_query: string;
+    };
+    options: {};
+};

package/dist/src/agents/ticloud.js

@@ -0,0 +1,15 @@
+import { TicloudPrompt } from "../prompts/ticloud.js";
+export const TicloudAgent = {
+    name: "ticloud",
+    mode: "primary",
+    description: "Internal oncall coordinator for TiCloud incidents",
+    prompt: TicloudPrompt,
+    permission: {
+        task: "allow",
+        todowrite: "allow",
+        question: "allow",
+        loki_log_query: "deny",
+        // clinic_cluster_query: "deny",
+    },
+    options: {},
+};

package/dist/src/index.d.ts

@@ -0,0 +1,5 @@
+declare const _default: {
+    id: string;
+    server: import("@opencode-ai/plugin").Plugin;
+};
+export default _default;

package/dist/src/index.js

@@ -0,0 +1,5 @@
+import { TiCloudOncallPlugin } from "./plugin.js";
+export default {
+    id: "ticloud-oncall",
+    server: TiCloudOncallPlugin,
+};

package/dist/src/lib/clinic-auth.d.ts

@@ -0,0 +1,6 @@
+export declare function readClinicApiKey(config: {
+    CLINIC_API_KEY?: string;
+}): string;
+export declare function resolveClinicBase(config: {
+    CLINIC_ENV?: string;
+}): string;

package/dist/src/lib/clinic-auth.js

@@ -0,0 +1,15 @@
+const CLINIC_BASES = {
+    dev: "https://dev-clinic.pingcap.com",
+    staging: "https://staging-clinic.pingcap.com",
+    prod: "https://clinic.pingcap.com",
+};
+export function readClinicApiKey(config) {
+    const key = config.CLINIC_API_KEY?.trim();
+    if (!key)
+        throw new Error("Missing CLINIC_API_KEY");
+    return key;
+}
+export function resolveClinicBase(config) {
+    const value = (config.CLINIC_ENV?.trim() || "prod");
+    return CLINIC_BASES[value] ?? CLINIC_BASES.prod;
+}

package/dist/src/lib/clinic-client.d.ts

@@ -0,0 +1 @@
+export declare function clinicRequest(path: string, init?: RequestInit): Promise<Response>;

package/dist/src/lib/clinic-client.js

@@ -0,0 +1,15 @@
+import { readClinicApiKey, resolveClinicBase } from "./clinic-auth.js";
+import { getPluginRuntimeConfig } from "./runtime-config.js";
+export async function clinicRequest(path, init = {}) {
+    const runtime = getPluginRuntimeConfig();
+    const base = resolveClinicBase(runtime);
+    const apiKey = readClinicApiKey(runtime);
+    return fetch(new URL(path, base), {
+        ...init,
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+            ...(init.headers ?? {}),
+        },
+    });
+}

package/dist/src/lib/result-format.d.ts

@@ -0,0 +1,4 @@
+export declare function summarizeLogLines(lines: string[], maxChars?: number): {
+    output: string;
+    truncated: boolean;
+};

package/dist/src/lib/result-format.js

@@ -0,0 +1,9 @@
+export function summarizeLogLines(lines, maxChars = 4000) {
+    const joined = lines.join("\n");
+    if (joined.length <= maxChars)
+        return { output: joined, truncated: false };
+    return {
+        output: joined.slice(0, maxChars) + "\n...truncated...",
+        truncated: true,
+    };
+}

package/dist/src/lib/runtime-config.d.ts

@@ -0,0 +1,8 @@
+export type PluginRuntimeConfig = {
+    CLINIC_API_KEY: string;
+    CLINIC_ENV?: string;
+    REPO_ROOTS?: string[];
+};
+export declare function setPluginRuntimeConfig(config: PluginRuntimeConfig): void;
+export declare function getPluginRuntimeConfig(): PluginRuntimeConfig;
+export declare function resetPluginRuntimeConfig(): void;

package/dist/src/lib/runtime-config.js

@@ -0,0 +1,12 @@
+let runtimeConfig;
+export function setPluginRuntimeConfig(config) {
+    runtimeConfig = config;
+}
+export function getPluginRuntimeConfig() {
+    if (!runtimeConfig)
+        throw new Error("Plugin runtime config is not initialized");
+    return runtimeConfig;
+}
+export function resetPluginRuntimeConfig() {
+    runtimeConfig = undefined;
+}

package/dist/src/lib/time.d.ts

@@ -0,0 +1 @@
+export declare function toUnixNanoseconds(input: string): string;

package/dist/src/lib/time.js

@@ -0,0 +1,6 @@
+export function toUnixNanoseconds(input) {
+    const millis = Date.parse(input);
+    if (Number.isNaN(millis))
+        throw new Error(`Invalid timestamp: ${input}`);
+    return `${BigInt(millis) * 1000000n}`;
+}

package/dist/src/plugin.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from "@opencode-ai/plugin";
+export declare const TiCloudOncallPlugin: Plugin;

package/dist/src/plugin.js

@@ -0,0 +1,59 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { LogAnalyzerAgent } from "./agents/log-analyzer.js";
+import { MetadataQuerierAgent } from "./agents/metadata-querier.js";
+import { TicloudAgent } from "./agents/ticloud.js";
+import { createTicloudPrompt } from "./prompts/ticloud.js";
+import { clinicClusterQueryTool } from "./tools/clinic-cluster-query.js";
+import { lokiLogQueryTool } from "./tools/loki-log-query.js";
+import { resetPluginRuntimeConfig, setPluginRuntimeConfig } from "./lib/runtime-config.js";
+const pluginDir = path.dirname(fileURLToPath(import.meta.url));
+const bundledSkillsDir = path.resolve(pluginDir, "../bundled-skills");
+export const TiCloudOncallPlugin = async (_input, options = {}) => {
+    const repetitionBySession = new Map();
+    const runtimeConfig = options;
+    if (runtimeConfig.CLINIC_API_KEY) {
+        setPluginRuntimeConfig(runtimeConfig);
+    }
+    return {
+        tool: {
+            loki_log_query: lokiLogQueryTool,
+            clinic_cluster_query: clinicClusterQueryTool,
+        },
+        config: async (config) => {
+            const mutableConfig = config;
+            config.agent = config.agent ?? {};
+            mutableConfig.skills = mutableConfig.skills ?? {};
+            mutableConfig.skills.paths = [...new Set([...(mutableConfig.skills.paths ?? []), bundledSkillsDir])];
+            mutableConfig.pluginRuntime = runtimeConfig;
+            config.agent.ticloud = {
+                ...TicloudAgent,
+                prompt: createTicloudPrompt(runtimeConfig.REPO_ROOTS),
+            };
+            config.agent["log-analyzer"] = LogAnalyzerAgent;
+            config.agent["metadata-querier"] = MetadataQuerierAgent;
+        },
+        "tool.execute.before": async (input, output) => {
+            const signature = JSON.stringify([input.tool, output.args]);
+            const prev = repetitionBySession.get(input.sessionID);
+            if (prev?.signature === signature) {
+                repetitionBySession.set(input.sessionID, { signature, count: prev.count + 1 });
+                return;
+            }
+            repetitionBySession.set(input.sessionID, { signature, count: 1 });
+        },
+        "tool.execute.after": async (input, output) => {
+            const signature = JSON.stringify([input.tool, input.args]);
+            const state = repetitionBySession.get(input.sessionID);
+            if (!state || state.signature !== signature || state.count < 3)
+                return;
+            output.metadata = {
+                ...(output.metadata ?? {}),
+                loop_guard: "Repeated identical tool call detected",
+            };
+        },
+        dispose: async () => {
+            resetPluginRuntimeConfig();
+        },
+    };
+};

package/dist/src/prompts/log-analyzer.d.ts

@@ -0,0 +1 @@
+export declare const LogAnalyzerPrompt = "You are a Loki log analysis specialist for TiDB Cloud Clinic. Find root causes of failures by querying Loki efficiently.\n\nUse loki_log_query for all log access.\nDo not use shell, python, curl, web fetch, or skills for log access.\nvendor, region, and cluster_id MUST be provided before querying logs.\nDo NOT iterate across vendors or regions.\nTreat cluster_id as a keyword filter, not a label.\nMax 10 queries per task.\n\nCore rules:\n- RFC3339 timestamps only.\n- Total time range must be strictly less than 7 days.\n- Never use {cluster_id=\"...\"} or {tidb_cluster_id=\"...\"} as labels.\n- Never hardcode label names or values. Discover first.\n- Fire independent queries in one message whenever possible.\n- Return root cause with 2-3 key log lines, not raw dumps.\n\nWorkflow: logs are not found in one shot. Narrow progressively.\n\n1. Meta information\n- Use the provided vendor and region to identify the endpoint.\n- Use only that endpoint.\n\n2. Reachability probe\n- First call labels action to verify the endpoint is alive and data exists.\n- If the endpoint probe is empty, report that immediately.\n\n3. Label and label-value discovery\n- Before content search, discover labels and key label values in parallel.\n- Prefer discovering: labels, app, namespace, and container.\n- Query label_values(\"namespace\") and label_values(\"container\") before any content query.\n\n4. Wide search\n- Start broad and shrink gradually.\n- Use keywords to narrow namespace, container/app, and time range.\n- First goal: confirm the target appears in logs at all.\n- Second goal: identify useful pivots such as T0, trace_id, namespace or container/app.\n\n5. Narrow search\n- Tighten the time range around T0.\n- Prefer more precise keywords such as trace_id or job_id when available.\n- If needed, adjust both keywords and time range to isolate the exact failure.\n\nFast fail rules:\n- If 3 consecutive queries with the same strategy return 0 results, switch strategy.\n- Example: text search to label-scoped search, or broad container search to namespace/app search.\n- If 3 consecutive queries on the same endpoint are all empty, return failure and stop trying.\n\nPractical defaults:\n- Default time range: last 24 hours when the user provides no window.\n- Never search more than 7 days.\n- Prioritize queries that improve precision, not volume.\n\nCommon label reference:\n- Reference only. Always verify via discovery.\n- Common namespaces: tidb-admin, prod-ms, cluster-ng-service, tidb-management-service\n- Premium / Essential v2 containers: cluster-service-ng, executor\n- Starter / Essential containers: manager, tidb-gateway\n- Starter / Essential app: serverless-svc\n\nTool parameter examples:\n\n1. Export failure with export_id\n- Probe: loki_log_query({ action: \"query_range\", vendor: \"alicloud\", region: \"ap-northeast-1\", cluster_tier: \"starter\", start_time: \"2026-06-03T12:00:00Z\", end_time: \"2026-06-03T12:10:00Z\", direction: \"backward\", limit: 3, logql: \"{container=~\".+\"}\" })\n- Discovery: loki_log_query({ action: \"label_values\", vendor: \"alicloud\", region: \"ap-northeast-1\", cluster_tier: \"starter\", label_name: \"container\" })\n- Wide search: loki_log_query({ action: \"query_range\", vendor: \"alicloud\", region: \"ap-northeast-1\", cluster_tier: \"starter\", start_time: \"2026-06-03T00:00:00Z\", end_time: \"2026-06-04T00:00:00Z\", direction: \"forward\", limit: 50, logql: \"{instance=~\"exp-abc123-.+\"}\" })\n- Narrow search: loki_log_query({ action: \"query_range\", vendor: \"alicloud\", region: \"ap-northeast-1\", cluster_tier: \"starter\", start_time: \"2026-06-03T09:49:00Z\", end_time: \"2026-06-03T10:10:00Z\", direction: \"backward\", limit: 50, logql: \"{container=\"executor\"} |= \"exp-abc123\" |~ \"(?i)(error|fail|fatal)\"\" })\n\n2. OOM (no job_id)\n- Probe: loki_log_query({ action: \"query_range\", vendor: \"aws\", region: \"us-east-1\", cluster_tier: \"starter\", start_time: \"2026-06-03T12:00:00Z\", end_time: \"2026-06-03T12:10:00Z\", direction: \"backward\", limit: 3, logql: \"{container=~\".+\"}\" })\n- Wide search: loki_log_query({ action: \"query_range\", vendor: \"aws\", region: \"us-east-1\", cluster_tier: \"starter\", start_time: \"2026-06-03T00:00:00Z\", end_time: \"2026-06-04T00:00:00Z\", direction: \"backward\", limit: 30, logql: \"{container=~\".+\"} |= \"10750825381049486289\"\" })\n- Narrow search: loki_log_query({ action: \"query_range\", vendor: \"aws\", region: \"us-east-1\", cluster_tier: \"starter\", start_time: \"2026-06-03T14:20:00Z\", end_time: \"2026-06-03T14:40:00Z\", direction: \"backward\", limit: 30, logql: \"{container=\"cluster-service-ng\"} |= \"10750825381049486289\" |~ \"(?i)(OOM|memory)\"\" })\n\n3. Slow connection with time window\n- Discovery: loki_log_query({ action: \"label_values\", vendor: \"aws\", region: \"us-east-1\", cluster_tier: \"starter\", label_name: \"container\" })\n- Wide search: loki_log_query({ action: \"query_range\", vendor: \"aws\", region: \"us-east-1\", cluster_tier: \"starter\", start_time: \"2026-06-03T14:00:00Z\", end_time: \"2026-06-03T15:00:00Z\", direction: \"backward\", limit: 50, logql: \"{container=~\".+\"} |= \"xxx\"\" })\n- Narrow search: loki_log_query({ action: \"query_range\", vendor: \"aws\", region: \"us-east-1\", cluster_tier: \"starter\", start_time: \"2026-06-03T14:20:00Z\", end_time: \"2026-06-03T14:40:00Z\", direction: \"backward\", limit: 30, logql: \"{container=\"tidb-gateway\"} |= \"xxx\" |~ \"(?i)(timeout|connection refused)\"\" })\n";

package/dist/src/prompts/log-analyzer.js

@@ -0,0 +1,78 @@
+export const LogAnalyzerPrompt = `You are a Loki log analysis specialist for TiDB Cloud Clinic. Find root causes of failures by querying Loki efficiently.
+
+Use loki_log_query for all log access.
+Do not use shell, python, curl, web fetch, or skills for log access.
+vendor, region, and cluster_id MUST be provided before querying logs.
+Do NOT iterate across vendors or regions.
+Treat cluster_id as a keyword filter, not a label.
+Max 10 queries per task.
+
+Core rules:
+- RFC3339 timestamps only.
+- Total time range must be strictly less than 7 days.
+- Never use {cluster_id="..."} or {tidb_cluster_id="..."} as labels.
+- Never hardcode label names or values. Discover first.
+- Fire independent queries in one message whenever possible.
+- Return root cause with 2-3 key log lines, not raw dumps.
+
+Workflow: logs are not found in one shot. Narrow progressively.
+
+1. Meta information
+- Use the provided vendor and region to identify the endpoint.
+- Use only that endpoint.
+
+2. Reachability probe
+- First call labels action to verify the endpoint is alive and data exists.
+- If the endpoint probe is empty, report that immediately.
+
+3. Label and label-value discovery
+- Before content search, discover labels and key label values in parallel.
+- Prefer discovering: labels, app, namespace, and container.
+- Query label_values("namespace") and label_values("container") before any content query.
+
+4. Wide search
+- Start broad and shrink gradually.
+- Use keywords to narrow namespace, container/app, and time range.
+- First goal: confirm the target appears in logs at all.
+- Second goal: identify useful pivots such as T0, trace_id, namespace or container/app.
+
+5. Narrow search
+- Tighten the time range around T0.
+- Prefer more precise keywords such as trace_id or job_id when available.
+- If needed, adjust both keywords and time range to isolate the exact failure.
+
+Fast fail rules:
+- If 3 consecutive queries with the same strategy return 0 results, switch strategy.
+- Example: text search to label-scoped search, or broad container search to namespace/app search.
+- If 3 consecutive queries on the same endpoint are all empty, return failure and stop trying.
+
+Practical defaults:
+- Default time range: last 24 hours when the user provides no window.
+- Never search more than 7 days.
+- Prioritize queries that improve precision, not volume.
+
+Common label reference:
+- Reference only. Always verify via discovery.
+- Common namespaces: tidb-admin, prod-ms, cluster-ng-service, tidb-management-service
+- Premium / Essential v2 containers: cluster-service-ng, executor
+- Starter / Essential containers: manager, tidb-gateway
+- Starter / Essential app: serverless-svc
+
+Tool parameter examples:
+
+1. Export failure with export_id
+- Probe: loki_log_query({ action: "query_range", vendor: "alicloud", region: "ap-northeast-1", cluster_tier: "starter", start_time: "2026-06-03T12:00:00Z", end_time: "2026-06-03T12:10:00Z", direction: "backward", limit: 3, logql: "{container=~\".+\"}" })
+- Discovery: loki_log_query({ action: "label_values", vendor: "alicloud", region: "ap-northeast-1", cluster_tier: "starter", label_name: "container" })
+- Wide search: loki_log_query({ action: "query_range", vendor: "alicloud", region: "ap-northeast-1", cluster_tier: "starter", start_time: "2026-06-03T00:00:00Z", end_time: "2026-06-04T00:00:00Z", direction: "forward", limit: 50, logql: "{instance=~\"exp-abc123-.+\"}" })
+- Narrow search: loki_log_query({ action: "query_range", vendor: "alicloud", region: "ap-northeast-1", cluster_tier: "starter", start_time: "2026-06-03T09:49:00Z", end_time: "2026-06-03T10:10:00Z", direction: "backward", limit: 50, logql: "{container=\"executor\"} |= \"exp-abc123\" |~ \"(?i)(error|fail|fatal)\"" })
+
+2. OOM (no job_id)
+- Probe: loki_log_query({ action: "query_range", vendor: "aws", region: "us-east-1", cluster_tier: "starter", start_time: "2026-06-03T12:00:00Z", end_time: "2026-06-03T12:10:00Z", direction: "backward", limit: 3, logql: "{container=~\".+\"}" })
+- Wide search: loki_log_query({ action: "query_range", vendor: "aws", region: "us-east-1", cluster_tier: "starter", start_time: "2026-06-03T00:00:00Z", end_time: "2026-06-04T00:00:00Z", direction: "backward", limit: 30, logql: "{container=~\".+\"} |= \"10750825381049486289\"" })
+- Narrow search: loki_log_query({ action: "query_range", vendor: "aws", region: "us-east-1", cluster_tier: "starter", start_time: "2026-06-03T14:20:00Z", end_time: "2026-06-03T14:40:00Z", direction: "backward", limit: 30, logql: "{container=\"cluster-service-ng\"} |= \"10750825381049486289\" |~ \"(?i)(OOM|memory)\"" })
+
+3. Slow connection with time window
+- Discovery: loki_log_query({ action: "label_values", vendor: "aws", region: "us-east-1", cluster_tier: "starter", label_name: "container" })
+- Wide search: loki_log_query({ action: "query_range", vendor: "aws", region: "us-east-1", cluster_tier: "starter", start_time: "2026-06-03T14:00:00Z", end_time: "2026-06-03T15:00:00Z", direction: "backward", limit: 50, logql: "{container=~\".+\"} |= \"xxx\"" })
+- Narrow search: loki_log_query({ action: "query_range", vendor: "aws", region: "us-east-1", cluster_tier: "starter", start_time: "2026-06-03T14:20:00Z", end_time: "2026-06-03T14:40:00Z", direction: "backward", limit: 30, logql: "{container=\"tidb-gateway\"} |= \"xxx\" |~ \"(?i)(timeout|connection refused)\"" })
+`;

package/dist/src/prompts/metadata-querier.d.ts

@@ -0,0 +1 @@
+export declare const MetadataQuerierPrompt = "You are a Clinic cluster metadata specialist.\n\nRules:\n- Prefer clinic_cluster_query whenever you need cluster information.\n- Do not use shell, python, curl, web fetch, or skills as a substitute for clinic_cluster_query when fetching cluster information.\n- If cluster_id is known, pass cluster_id.\n- If cluster_id is unknown, pass query.\n- Return the cluster information you can retrieve. If a field cannot be retrieved, omit it.\n- Return concise operational summaries.\n";

package/dist/src/prompts/metadata-querier.js

@@ -0,0 +1,10 @@
+export const MetadataQuerierPrompt = `You are a Clinic cluster metadata specialist.
+
+Rules:
+- Prefer clinic_cluster_query whenever you need cluster information.
+- Do not use shell, python, curl, web fetch, or skills as a substitute for clinic_cluster_query when fetching cluster information.
+- If cluster_id is known, pass cluster_id.
+- If cluster_id is unknown, pass query.
+- Return the cluster information you can retrieve. If a field cannot be retrieved, omit it.
+- Return concise operational summaries.
+`;

package/dist/src/prompts/ticloud.d.ts

@@ -0,0 +1,2 @@
+export declare function createTicloudPrompt(repoRoots?: string[]): string;
+export declare const TicloudPrompt: string;

package/dist/src/prompts/ticloud.js

@@ -0,0 +1,50 @@
+export function createTicloudPrompt(repoRoots) {
+    const renderedRoots = repoRoots?.length ? repoRoots.join("\n- ") : "(not set)";
+    return `You are an internal TiCloud oncall coordinator.
+
+Goals:
+- Ground diagnosis with cluster metadata before interpreting logs.
+- Use log evidence to validate hypotheses.
+- Reuse the built-in explore subagent for local code search only.
+- State uncertainty explicitly.
+
+Logging rules:
+- Use only Loki direct API for log queries.
+- Use metadata to obtain region, vendor, and tier(deploy_type) before dispatching log analysis.
+- When you need cluster information, use clinic_cluster_query rather than relying on skills.
+- When cluster_id is known, prefer clinic_cluster_query with exact cluster_id lookup.
+- When you need logs, prefer loki_log_query rather than shell, python, curl, or skills.
+- Do not query logs for more than 7 days at a time.
+
+Dispatching log-analyzer:
+- ALWAYS pass vendor, region, and cluster_id as structured context when dispatching log-analyzer.
+- Always pass vendor, region, and cluster_id when dispatching log-analyzer.
+- Example dispatch message: "Query logs for cluster_id=123, vendor=alicloud, region=ap-northeast-1, time range=..., symptom=..."
+- The log-analyzer will refuse to query if vendor, region, or cluster_id is missing.
+
+Code search rules:
+- The plugin provides REPO_ROOTS as candidate repository roots.
+- If REPO_ROOTS is missing or the candidate repository set cannot be identified confidently, ask the user to provide it.
+- When dispatching explore for code search, search only inside the narrowed candidate repositories selected from REPO_ROOTS.
+- Only dispatch explore when the candidate repo set is reasonably small.
+- Do not search the whole workspace when the repository path is unknown.
+- Configured REPO_ROOTS:
+- ${renderedRoots}
+
+Repo search heuristics:
+- Prefer code search terms extracted from logs, especially error phrases, app names, container names, namespace names, and unique stack trace fragments.
+- If logs already reveal likely app/container names, pass those as search hints to explore.
+- Use metadata first, then logs, then code; code search should be a targeted follow-up, not a blind scan.
+- Treat REPO_ROOTS as a candidate repository roots pool and narrow it before code search.
+
+Workflow:
+1. Identify missing context.
+2. Dispatch metadata-querier when cluster identity, region, vendor, or tier is unclear. MUST complete this before log analysis.
+3. Dispatch log-analyzer ONLY after metadata is resolved. Pass vendor, region, cluster_id, and cluster_tier explicitly.
+4. Use metadata and log clues to narrow candidate repositories from REPO_ROOTS.
+5. Ask for REPO_ROOTS before code search if it is missing or still too ambiguous.
+6. Dispatch explore only when code evidence is needed, and constrain the search to the narrowed candidate repositories.
+7. Summarize findings, evidence, likely cause, and next steps.
+`;
+}
+export const TicloudPrompt = createTicloudPrompt();

package/dist/src/tools/clinic-cluster-query.d.ts

@@ -0,0 +1,3 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+export declare function resetClinicClusterQueryCache(): void;
+export declare const clinicClusterQueryTool: ToolDefinition;

package/dist/src/tools/clinic-cluster-query.js

@@ -0,0 +1,127 @@
+import { tool } from "@opencode-ai/plugin";
+import { clinicRequest } from "../lib/clinic-client.js";
+const orgIDCache = new Map();
+export function resetClinicClusterQueryCache() {
+    orgIDCache.clear();
+}
+function getClusterItems(payload) {
+    return payload?.items ?? payload?.data?.clusters ?? payload?.clusters ?? [];
+}
+function getClusterID(cluster) {
+    return cluster?.id ?? cluster?.clusterID ?? cluster?.clusterId ?? cluster?.cluster_id;
+}
+function getClusterName(cluster) {
+    return cluster?.clusterName ?? cluster?.name;
+}
+function getClusterStatus(cluster) {
+    return cluster?.clusterStatus ?? cluster?.status;
+}
+function getClusterDeployType(cluster) {
+    return cluster?.clusterDeployType ?? cluster?.deployType;
+}
+function getClusterDeployTypeV2(cluster) {
+    return cluster?.clusterDeployTypeV2 ?? cluster?.deployTypeV2;
+}
+function getClusterProvider(cluster) {
+    return cluster?.clusterProviderName ?? cluster?.provider;
+}
+function getClusterRegion(cluster) {
+    return cluster?.clusterRegionName ?? cluster?.region;
+}
+function cacheOrgID(cluster) {
+    const clusterID = getClusterID(cluster);
+    const orgID = cluster?.orgID;
+    if (clusterID && orgID)
+        orgIDCache.set(clusterID, orgID);
+}
+function formatCluster(cluster) {
+    return [
+        `clusterID=${getClusterID(cluster) ?? "unknown"}`,
+        `name=${getClusterName(cluster) ?? "unknown"}`,
+        getClusterStatus(cluster) ? `status=${getClusterStatus(cluster)}` : undefined,
+        getClusterDeployTypeV2(cluster) ? `deployTypeV2=${getClusterDeployTypeV2(cluster)}` : undefined,
+        getClusterDeployType(cluster) ? `deployType=${getClusterDeployType(cluster)}` : undefined,
+        getClusterProvider(cluster) ? `provider=${getClusterProvider(cluster)}` : undefined,
+        getClusterRegion(cluster) ? `region=${getClusterRegion(cluster)}` : undefined,
+        cluster.clusterVersion ?? cluster.version ? `version=${cluster.clusterVersion ?? cluster.version}` : undefined,
+        cluster.projectID ? `projectID=${cluster.projectID}` : undefined,
+        cluster.tenantID ? `tenantID=${cluster.tenantID}` : undefined,
+        cluster.parentID ? `parentID=${cluster.parentID}` : undefined,
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+function formatClusterList(payload) {
+    const items = getClusterItems(payload);
+    if (!items.length)
+        return "No matching clusters found.";
+    if (items.length === 1 && getClusterID(items[0]))
+        return formatCluster(items[0]);
+    return items
+        .slice(0, 10)
+        .map((item) => [
+        `- ${getClusterID(item)}: ${getClusterName(item) ?? "unknown"}`,
+        getClusterDeployTypeV2(item) ? `type=${getClusterDeployTypeV2(item)}` : undefined,
+        getClusterProvider(item) ? `provider=${getClusterProvider(item)}` : undefined,
+        getClusterRegion(item) ? `region=${getClusterRegion(item)}` : undefined,
+        item.tenantID ? `tenantID=${item.tenantID}` : undefined,
+    ]
+        .filter(Boolean)
+        .join(" "))
+        .join("\n");
+}
+async function searchClusterByID(clusterID) {
+    const url = new URL("/clinic/api/v1/dashboard/clusters", "https://placeholder.local");
+    url.searchParams.set("cluster_id", clusterID);
+    url.searchParams.set("show_deleted", "true");
+    url.searchParams.set("limit", "1");
+    const response = await clinicRequest(url.pathname + url.search);
+    const data = await response.json();
+    const cluster = getClusterItems(data).find((item) => getClusterID(item) === clusterID);
+    if (cluster)
+        cacheOrgID(cluster);
+    return cluster;
+}
+async function resolveOrgID(clusterID) {
+    const cached = orgIDCache.get(clusterID);
+    if (cached)
+        return cached;
+    const cluster = await searchClusterByID(clusterID);
+    const orgID = cluster?.orgID;
+    if (orgID)
+        orgIDCache.set(clusterID, orgID);
+    return orgID;
+}
+async function fetchClusterDetails(clusterID) {
+    const summary = await searchClusterByID(clusterID);
+    if (!summary)
+        return undefined;
+    const orgID = await resolveOrgID(clusterID);
+    if (!orgID)
+        return summary;
+    const response = await clinicRequest(`/clinic/api/v1/orgs/${orgID}/clusters/${clusterID}`);
+    const detail = await response.json();
+    cacheOrgID(detail?.data ?? detail);
+    return detail?.data ?? detail ?? summary;
+}
+export const clinicClusterQueryTool = tool({
+    description: "Query TiDB Cloud cluster metadata via Clinic API",
+    args: {
+        cluster_id: tool.schema.string().optional(),
+        query: tool.schema.string().optional(),
+    },
+    async execute(args) {
+        if (args.cluster_id) {
+            const cluster = await fetchClusterDetails(args.cluster_id);
+            if (!cluster)
+                return "No matching clusters found.";
+            return formatCluster(cluster);
+        }
+        if (!args.query)
+            throw new Error("query requires cluster_id or query");
+        const url = new URL("/clinic/api/v1/dashboard/clusters", "https://placeholder.local");
+        url.searchParams.set("query", args.query);
+        const response = await clinicRequest(url.pathname + url.search);
+        return formatClusterList(await response.json());
+    },
+});

package/dist/src/tools/loki-log-query.d.ts

@@ -0,0 +1,2 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+export declare const lokiLogQueryTool: ToolDefinition;

package/dist/src/tools/loki-log-query.js

@@ -0,0 +1,119 @@
+import { tool } from "@opencode-ai/plugin";
+import { summarizeLogLines } from "../lib/result-format.js";
+import { toUnixNanoseconds } from "../lib/time.js";
+const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+function isPremiumTier(tier) {
+    return tier === "premium" || tier === "nextgen";
+}
+function buildBaseCandidates(region, vendor, variant, tier) {
+    const standard = `https://www.ds.${region}.${vendor}.observability.tidbcloud.com/loki/self-monitoring/loki/api/v1`;
+    const ng = `https://www.ds.${region}-ng.${vendor}.observability.tidbcloud.com/loki/self-monitoring/loki/api/v1`;
+    const premium = `https://www.ds.${region}-premium.${vendor}.observability.tidbcloud.com/loki/self-monitoring/loki/api/v1`;
+    if (variant === "standard")
+        return [standard];
+    if (variant === "ng")
+        return [ng];
+    if (variant === "premium")
+        return [premium];
+    if (isPremiumTier(tier))
+        return [ng, premium];
+    return [standard];
+}
+async function requestWithFallback(candidates, pathname, searchParams) {
+    let lastError;
+    const errors = [];
+    for (const base of candidates) {
+        const url = new URL(pathname, `${base}/`);
+        url.search = searchParams.toString();
+        try {
+            const response = await fetch(url);
+            if (response.ok)
+                return response;
+            const body = await response.text().catch(() => "");
+            errors.push(`${url}: HTTP ${response.status} - ${body.slice(0, 500)}`);
+            lastError = new Error(`Loki endpoint returned ${response.status} for ${url}`);
+        }
+        catch (err) {
+            errors.push(`${url}: ${err instanceof Error ? err.message : String(err)}`);
+            lastError = err instanceof Error ? err : new Error(String(err));
+        }
+    }
+    throw new Error(`Failed to reach Loki endpoint. Errors:\n${errors.join("\n")}`);
+}
+function validateTimeRange(startTime, endTime) {
+    if (!startTime || !endTime)
+        return;
+    const start = Date.parse(startTime);
+    const end = Date.parse(endTime);
+    if (Number.isNaN(start) || Number.isNaN(end))
+        throw new Error("Invalid input: start_time and end_time must be valid timestamps.");
+    if (end < start)
+        throw new Error("Invalid input: end_time must be later than start_time.");
+    if (end - start > SEVEN_DAYS_MS) {
+        throw new Error("Invalid input: Loki direct query time range must be within 7 days.");
+    }
+}
+function formatLabelList(payload) {
+    const items = payload?.data ?? [];
+    if (!items.length)
+        return "No labels found.";
+    return items.join("\n");
+}
+function formatLokiPayload(payload) {
+    const streams = payload?.data?.result ?? [];
+    if (!streams.length)
+        return "No log lines matched the query. Check time range, labels, or whether the filter is too narrow.";
+    const lines = streams.flatMap((stream, index) => {
+        const labels = Object.entries(stream.stream ?? {})
+            .map(([key, value]) => `${key}=${value}`)
+            .join(" ");
+        const header = labels ? `stream ${index + 1}: ${labels}` : `stream ${index + 1}`;
+        const values = (stream.values ?? []).map((entry) => `${entry[0]} => ${entry[1]}`);
+        return [header, ...values];
+    });
+    const { output } = summarizeLogLines(lines);
+    return `Matched ${streams.length} streams\n\n${output}`;
+}
+export const lokiLogQueryTool = tool({
+    description: "Query Loki direct API for labels, label values, or query ranges.",
+    args: {
+        action: tool.schema.enum(["labels", "label_values", "query_range"]),
+        region: tool.schema.string(),
+        vendor: tool.schema.enum(["aws", "alicloud", "gcp", "azure"]),
+        endpoint_variant: tool.schema.enum(["standard", "ng", "premium", "auto"]).default("auto"),
+        cluster_tier: tool.schema.string().optional(),
+        label_name: tool.schema.string().optional(),
+        logql: tool.schema.string().optional(),
+        start_time: tool.schema.string().optional(),
+        end_time: tool.schema.string().optional(),
+        limit: tool.schema.number().int().positive().default(100),
+        direction: tool.schema.enum(["forward", "backward"]).default("backward"),
+    },
+    async execute(args) {
+        validateTimeRange(args.start_time, args.end_time);
+        const candidates = buildBaseCandidates(args.region, args.vendor, args.endpoint_variant, args.cluster_tier);
+        const params = new URLSearchParams();
+        if (args.start_time)
+            params.set("start", toUnixNanoseconds(args.start_time));
+        if (args.end_time)
+            params.set("end", toUnixNanoseconds(args.end_time));
+        if (args.action === "labels") {
+            const response = await requestWithFallback(candidates, "labels", params);
+            return formatLabelList(await response.json());
+        }
+        if (args.action === "label_values") {
+            if (!args.label_name)
+                throw new Error("Invalid input: label_name is required for label_values.");
+            const response = await requestWithFallback(candidates, `label/${args.label_name}/values`, params);
+            return formatLabelList(await response.json());
+        }
+        if (!args.logql || !args.start_time || !args.end_time) {
+            throw new Error("Invalid input: query_range requires logql, start_time, and end_time.");
+        }
+        params.set("query", args.logql);
+        params.set("limit", String(args.limit));
+        params.set("direction", args.direction ?? "backward");
+        const response = await requestWithFallback(candidates, "query_range", params);
+        return formatLokiPayload(await response.json());
+    },
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@shiyuhang0/ticloud-oncall",
+  "version": "0.1.0",
+  "description": "TiDB Cloud oncall plugin for opencode",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/src",
+    "bundled-skills"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.15.13",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.30",
+    "typescript": "^5.8.3",
+    "vitest": "^2.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}