@tplog/pi-zendy 0.2.17 → 0.3.0

package/extensions/tools.ts

@@ -0,0 +1,190 @@
+// Zendy tools — LLM-callable wrappers over direct API clients.
+// Loaded by jiti as part of the zendy extension.
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import * as zendesk from "../dist/clients/zendesk.js";
+import * as helm from "../dist/clients/helm-watchdog.js";
+import * as kg from "../dist/clients/zendesk-kg.js";
+
+function textResult(text: string, details: Record<string, unknown> = {}) {
+  return { content: [{ type: "text" as const, text }], details };
+}
+
+function registerZendeskTools(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "zendy_ticket_get",
+    label: "Zendy Ticket",
+    description: "Fetch a Zendesk ticket with comments and user info via direct API. Prefer this over any CLI command for ticket analysis.",
+    promptSnippet: "Fetch Zendesk ticket, comments, and user details with zendy_ticket_get.",
+    promptGuidelines: [
+      "Use zendy_ticket_get when the user provides a Zendesk ticket ID. It returns ticket metadata, comments, requester, and assignee.",
+      "Base conclusions on the returned ticket and comments; do not rely on external commands.",
+    ],
+    parameters: Type.Object({
+      ticketId: Type.Number({ description: "Zendesk ticket ID" }),
+    }),
+    async execute(_toolCallId: string, params: { ticketId: number }, signal?: AbortSignal) {
+      const result = await zendesk.getTicketFull(params.ticketId, signal);
+      return textResult(
+        `Fetched Zendesk ticket #${result.ticket.id}: "${result.ticket.subject}" (${result.ticket.status}), ${result.comments?.length ?? 0} comments.`,
+        {
+          ticket: result.ticket,
+          comments: result.comments,
+          requester: result.requester,
+          assignee: result.assignee,
+        },
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "zendy_ticket_search",
+    label: "Zendy Search",
+    description: "Search Zendesk tickets via direct API. For fresh/live Zendesk lookups, not historical semantic retrieval.",
+    promptSnippet: "Search live Zendesk tickets with zendy_ticket_search.",
+    parameters: Type.Object({
+      query: Type.String({ description: "Zendesk search query string" }),
+    }),
+    async execute(_toolCallId: string, params: { query: string }, signal?: AbortSignal) {
+      const result = await zendesk.searchTickets(params.query, signal);
+      return textResult(`Zendesk search returned ${result.count} results.`, { results: result.results, count: result.count });
+    },
+  });
+}
+
+function registerHelmTools(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "zendy_helm_get",
+    label: "Zendy Helm",
+    description: "Query Dify Helm Watchdog API for chart metadata, values.yaml, images, and validation. Always provide the exact chart version.",
+    promptSnippet: "Query Helm chart data with zendy_helm_get.",
+    promptGuidelines: [
+      "Use zendy_helm_get to query Dify Helm chart metadata. Always pass the customer's exact version.",
+      "Defaults change between versions — never assume a config value without checking the right version.",
+    ],
+    parameters: Type.Object({
+      resource: Type.Union([
+        Type.Literal("version"),
+        Type.Literal("values"),
+        Type.Literal("images"),
+        Type.Literal("validation"),
+        Type.Literal("latest"),
+        Type.Literal("versions"),
+        Type.Literal("cache"),
+      ], { description: "Resource to fetch" }),
+      version: Type.Optional(Type.String({ description: "Chart version. Required for: version, values, images, validation" })),
+      validateImages: Type.Optional(Type.Boolean({ description: "For images: include pull-status validation", default: false })),
+      status: Type.Optional(Type.String({ description: "For validation: filter by MISSING etc." })),
+      versionOnly: Type.Optional(Type.Boolean({ description: "For latest: return plain version string only", default: false })),
+    }),
+    async execute(_toolCallId: string, params: {
+      resource: string;
+      version?: string;
+      validateImages?: boolean;
+      status?: string;
+      versionOnly?: boolean;
+    }, signal?: AbortSignal) {
+      const needsVersion = ["version", "values", "images", "validation"].includes(params.resource);
+      if (needsVersion && !params.version) {
+        throw new Error(`version is required when resource=${params.resource}`);
+      }
+
+      switch (params.resource) {
+        case "version": {
+          const data = await helm.getVersion(params.version!, signal);
+          return textResult(`Helm Watchdog version metadata for ${params.version}.`, { version: params.version, data });
+        }
+        case "values": {
+          const data = await helm.getValues(params.version!, signal);
+          return textResult(`Helm Watchdog values.yaml for ${params.version}.`, { version: params.version, data });
+        }
+        case "images": {
+          const data = await helm.getImages(params.version!, params.validateImages, signal);
+          return textResult(`Helm Watchdog images for ${params.version} (${data.length} images).`, { version: params.version, images: data });
+        }
+        case "validation": {
+          const data = await helm.getValidation(params.version!, params.status, signal);
+          return textResult(`Helm Watchdog validation for ${params.version}.`, { version: params.version, results: data });
+        }
+        case "latest": {
+          const data = await helm.getLatest(params.versionOnly, signal);
+          return textResult("Helm Watchdog latest version.", { data });
+        }
+        case "versions": {
+          const data = await helm.listVersions(signal);
+          return textResult(`Helm Watchdog cached versions (${data.length} entries).`, { versions: data });
+        }
+        case "cache": {
+          const data = await helm.getCache(signal);
+          return textResult("Helm Watchdog cache metadata.", { data });
+        }
+      }
+    },
+  });
+}
+
+function registerKnowledgeGraphTools(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "zendy_kg_search",
+    label: "Zendy KG",
+    description: "Search the Zendesk Knowledge Graph for historically similar tickets via direct API. Always cite ticketId values from results.",
+    promptSnippet: "Search historical similar tickets with zendy_kg_search.",
+    promptGuidelines: [
+      "Use zendy_kg_search for historical similar-ticket retrieval. Cite ticketId values when summarizing.",
+      "Empty results do not prove no similar issue exists — the KG is a snapshot, not live Zendesk.",
+    ],
+    parameters: Type.Object({
+      query: Type.String({ description: "Natural-language description of the issue" }),
+      limit: Type.Optional(Type.Number({ description: "Max results 1-20", default: 5 })),
+      version: Type.Optional(Type.String({ description: "Filter by Dify version mentioned in tickets" })),
+      priority: Type.Optional(Type.String({ description: "Filter: low, normal, high, urgent" })),
+      status: Type.Optional(Type.String({ description: "Filter by ticket status: open, closed, pending, etc." })),
+    }),
+    async execute(_toolCallId: string, params: {
+      query: string;
+      limit?: number;
+      version?: string;
+      priority?: string;
+      status?: string;
+    }, signal?: AbortSignal) {
+      const limit = Math.min(Math.max(Math.trunc(params.limit ?? 5), 1), 20);
+      const result = await kg.search({
+        query: params.query,
+        topK: limit,
+        filter: {
+          ...(params.version ? { versions: [params.version] } : {}),
+          ...(params.priority ? { priority: params.priority } : {}),
+          ...(params.status ? { status: params.status } : {}),
+        },
+      }, signal);
+      return textResult(
+        `KG search returned ${result.results.length} results for "${result.queryText}". Cite ticketId values from details.results.`,
+        { results: result.results, queryText: result.queryText },
+      );
+    },
+  });
+}
+
+function registerSourceTools(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "zendy_source_status",
+    label: "Zendy Source Status",
+    description: "Report the zendy source-analysis workspace path and whether source cloning is authorized.",
+    promptSnippet: "Check source workspace status with zendy_source_status.",
+    parameters: Type.Object({}),
+    async execute() {
+      return textResult("Source workspace status.", {
+        workspace: process.env["ZENDY_SRC_DIR"] ?? null,
+        note: "Source cloning/search requires explicit user permission per zendy workflow rules. Ask before cloning private source.",
+      });
+    },
+  });
+}
+
+export function registerAllTools(pi: ExtensionAPI): void {
+  registerZendeskTools(pi);
+  registerHelmTools(pi);
+  registerKnowledgeGraphTools(pi);
+  registerSourceTools(pi);
+}

package/extensions/zendy.ts

@@ -0,0 +1,140 @@
+/**
+ * Zendy — unified pi extension entry point.
+ *
+ * Provides:
+ *   - Tools (LLM-callable): zendy_ticket_get, zendy_ticket_search,
+ *     zendy_helm_get, zendy_kg_search, zendy_source_status
+ *   - Slash commands: /zendy-config, /zendy-status, /zendy-cleanup
+ *   - Session lifecycle: workspace dir + cleanup + orphan sweep
+ *   - Custom header on session start
+ *
+ * No external CLI dependencies (zcli, zendesk-kg) required.
+ * All data access is through direct REST APIs.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerAllTools } from "./tools.js";
+import { registerAllCommands } from "./commands.js";
+import { mkdirSync, rmSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+// ── Constants ──────────────────────────────────────────────────────────
+
+const BASE_DIR = "/tmp";
+const SESSION_PREFIX = "zendy-session-";
+const WIPE_PREFIXES = ["dify-", SESSION_PREFIX];
+
+// ── Session workspace helpers ──────────────────────────────────────────
+
+function parseSessionDir(name: string): { pid: number } | null {
+  const m = /^zendy-session-(\d+)-(\d+)$/.exec(name);
+  return m ? { pid: parseInt(m[1]!, 10) } : null;
+}
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return (e as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+function safeRmrf(path: string): boolean {
+  try {
+    rmSync(path, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function sweepOrphans(base: string, exclude: string): string[] {
+  let entries;
+  try {
+    entries = readdirSync(base, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const removed: string[] = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const info = parseSessionDir(e.name);
+    if (!info) continue;
+    const full = join(base, e.name);
+    if (full === exclude) continue;
+    if (isProcessAlive(info.pid)) continue;
+    if (safeRmrf(full)) removed.push(full);
+  }
+  return removed;
+}
+
+// ── ASCII header ───────────────────────────────────────────────────────
+
+const HEADER = `
+███████╗███████╗███╗   ██╗██████╗ ██╗   ██╗
+╚══███╔╝██╔════╝████╗  ██║██╔══██╗╚██╗ ██╔╝
+  ███╔╝ █████╗  ██╔██╗ ██║██║  ██║ ╚████╔╝
+ ███╔╝  ██╔══╝  ██║╚██╗██║██║  ██║  ╚██╔╝
+███████╗███████╗██║ ╚████║██████╔╝   ██║
+╚══════╝╚══════╝╚═╝  ╚═══╝╚═════╝    ╚═╝
+Dify Enterprise Support Harness
+`;
+
+// ── Extension entry ────────────────────────────────────────────────────
+
+export default function (pi: ExtensionAPI) {
+  // ── Tools & Commands ────────────────────────────────────────────────
+  
+  registerAllTools(pi);
+  registerAllCommands(pi);
+
+  // ── Session lifecycle ───────────────────────────────────────────────
+
+  const ts = Date.now();
+  const sessionDir = join(BASE_DIR, `${SESSION_PREFIX}${process.pid}-${ts}`);
+  let cleanedUp = false;
+
+  function ensureDir(): void {
+    try {
+      mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
+    } catch {
+      // non-fatal
+    }
+  }
+
+  function cleanupSession(): void {
+    if (cleanedUp) return;
+    cleanedUp = true;
+    safeRmrf(sessionDir);
+  }
+
+  process.on("exit", cleanupSession);
+  process.on("SIGINT", () => { cleanupSession(); process.exit(130); });
+  process.on("SIGTERM", () => { cleanupSession(); process.exit(143); });
+  process.on("uncaughtException", (err) => {
+    cleanupSession();
+    console.error(err);
+    process.exit(1);
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    ensureDir();
+    process.env["ZENDY_SRC_DIR"] = sessionDir;
+
+    // Custom header
+    if (ctx.hasUI) {
+      ctx.ui.notify(HEADER, "info");
+    }
+
+    // Sweep orphan session dirs
+    const removed = sweepOrphans(BASE_DIR, sessionDir);
+    if (ctx.hasUI && removed.length > 0) {
+      ctx.ui.notify(`[zendy] swept ${removed.length} orphan session dir(s)`, "info");
+    }
+  });
+
+  pi.on("session_shutdown", async () => {
+    cleanupSession();
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tplog/pi-zendy",
-  "version": "0.2.17",
+  "version": "0.3.0",
   "description": "Pi package for Dify Enterprise support ticket analysis",
   "repository": {
     "type": "git",
@@ -18,16 +18,11 @@
   ],
   "pi": {
     "extensions": [
-      "./extensions"
-    ],
-    "skills": [
-      "./skills"
+      "./extensions/zendy.ts"
     ]
   },
   "files": [
     "dist",
-    "agents.md",
-    "skills",
     "extensions"
   ],
   "publishConfig": {
@@ -37,8 +32,7 @@
     "build": "tsc",
     "test": "tsc && node --test test/*.test.mjs",
     "prepare": "tsc",
-    "prepublishOnly": "tsc",
-    "postinstall": "command -v zendesk-kg >/dev/null 2>&1 || (curl -fsSL https://raw.githubusercontent.com/sorphwer/zendesk-kg-cli-release/main/install.sh | sh || true)"
+    "prepublishOnly": "tsc"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"

package/agents.md

@@ -1,118 +0,0 @@
-# zendy
-
-Internal support engineering harness for Dify Enterprise. Powered by pi.
-
-## Identity
-
-zendy is a Pi package that loads a fixed set of skills + extensions on top of [pi](https://pi.dev) so a support engineer can analyze a Zendesk ticket end-to-end without leaving the terminal. The published npm package is `@tplog/pi-zendy`; the source is the private repo `tplog/pi-zendy`.
-
-## What zendy ships with
-
-Three skills, loaded by default:
-
-- `zendesk-cli` — Pull Zendesk ticket metadata and comment threads via `zcli`
-- `helm-watchdog` — Query Dify Helm chart values, images, and validation by version
-- `source-check` — Clone and analyze Dify source code (only when the user explicitly asks)
-
-One additional opt-in skill:
-
-- `zendesk-kg` — Hybrid retrieval over a Zendesk Knowledge Graph for cross-ticket / similar-issue lookups
-
-Two extensions:
-
-- `custom-header` — ZENDY ASCII art on session start
-- `source-cleanup` — Per-session `/tmp/zendy-session-<pid>-<ts>/` directory + automatic wipe on exit; orphan sweep on next start
-
-One slash command beyond what pi gives you: `/status` runs `zendy preflight --json` and renders a per-source connectivity check (pi auth / Zendesk / GitHub / zendesk-kg).
-
-## Typical workflow
-
-1. User gives a ticket number → use `zcli` to pull ticket + comments
-2. Identify the customer's Dify version from ticket fields
-3. Pull the corresponding Helm chart values via the helm-watchdog API
-4. If the issue requires code-level analysis, the user will say so → use the `source-check` skill
-5. (optional) Use `zendesk-kg search` to find similar past tickets if cross-ticket evidence helps
-6. Synthesize findings and draft a reply in the ticket's language
-
-## Behavior rules
-
-- **Never guess.** Base conclusions on actual data — ticket fields, values.yaml, source code, ticket-graph results. State clearly what is fact vs inference.
-- **Don't recommend solutions you haven't verified.** If you haven't confirmed something in the code or docs, say so.
-- **Version matters.** Always check the customer's exact Dify version — defaults and behavior change between releases.
-- **Reply drafts match the ticket language.** Detect the language from the ticket thread (Japanese, Chinese, or English) and draft in the same language with appropriate business tone.
-- **Suggest source-check when confidence is low.** If your analysis cannot be confirmed from config alone, proactively ask the user: "需要我去源码确认吗？" Don't clone without permission, but suggest it instead of leaving uncertainty unresolved.
-- **Inspect before filtering.** When calling an unfamiliar API for the first time, look at the response structure (`| jq 'type'`, `| jq '.[0] | keys'`, or `| head`) before writing filter expressions. Never assume field names.
-- **Skills are APIs, not CLIs (mostly).** `helm-watchdog` is an HTTP API (use `curl`); `zcli` is a CLI; `zendesk-kg` is a CLI. Read the skill's Quick Reference before your first call. Do not guess command names.
-- **Auto-install missing dependencies.** If `zcli` or `zendesk-kg` is not found, run their installer automatically and continue. Don't ask — this is an internal tool, all dependencies are expected. (`zendy` v0.2.13+ also auto-installs `zendesk-kg` via postinstall.)
-- **Cite sources when you summarize.** When using `zendesk-kg search` results, surface the original `ticketId`s — the engineer wants to read the source ticket, not just your synthesis.
-- **`zendesk-kg health` is currently unreliable.** The retriever's `/health` endpoint sits behind a 302 → login page even though `/search` is API-key-authenticated and works. Don't gate retries on `health`. Only `health: ok` is a real signal; `health: unreachable` is inconclusive.
-
-## Development flow
-
-The development of zendy itself follows three rules. These are non-negotiable.
-
-1. **`main` is always the latest source of truth.** All accepted changes land on `main`; no long-lived divergent branches.
-2. **Tags drive releases.** Pushing a `vX.Y.Z` tag triggers `.github/workflows/publish.yml`, which verifies `tag == package.json.version`, runs tests, and `npm publish --access public`. The npm registry is downstream of the tag, never the other way around.
-3. **Every push to `main` goes through a Pull Request.** No direct pushes to `main`, no exceptions. This includes `chore: release X.Y.Z` version-bump commits — they too open a branch + PR before being merged.
-
-### Concrete steps for a code change
-
-```
-1. Create a branch:                git checkout -b <type>/<short-name>
-2. Make the change locally
-3. Verify locally:                 npm test (or relevant manual checks)
-4. Commit + push the branch:       git push -u origin <branch>
-5. Open a PR:                      gh pr create --title "..." --body "..."
-6. Wait for the human owner's review/merge
-7. After merge, locally:           git checkout main && git pull
-```
-
-Do not bump `package.json.version` in the same PR as a feature/fix unless the human owner asked for it. Version bumps belong in their own PR.
-
-### Concrete steps for a release
-
-```
-1. main has the merged feature/fix commits you want to ship
-2. Branch:                         git checkout -b chore/release-X.Y.Z
-3. Bump:                           edit package.json (version)
-                                   npm install --package-lock-only
-4. Commit + push branch:           git push -u origin chore/release-X.Y.Z
-5. Open the release PR:            gh pr create --title "chore: release X.Y.Z" ...
-6. Wait for merge
-7. After merge, on local main:     git checkout main && git pull
-                                   git tag vX.Y.Z
-                                   git push origin vX.Y.Z
-8. Watch the workflow:             gh run watch <id> --exit-status
-9. Verify on npm:                  npm view @tplog/pi-zendy version
-10. Cut a GitHub Release:          gh release create vX.Y.Z --title "..." --notes "..."
-11. Announce in #zendy with the GH Release URL.
-```
-
-Release timing (whether to tag now vs accumulate more PRs first) is a **human decision**. Agents should not unilaterally tag — ask the human owner before step 7.
-
-### Test machine handoff
-
-The local sandbox where an agent develops is **not** the same as the human's test machine. To let the human verify a not-yet-merged change without going through GitHub auth:
-
-```
-1. On the agent machine, after `npm test` passes locally:
-       npm pack
-       slock attachment upload --path tplog-zendy-<version>.tgz --channel "#zendy"
-2. Tell the human: `npm install -g <downloaded-tarball-path>`
-```
-
-This bypasses `npm install -g git+ssh://...#main`, which currently fails because npm 10/11 doesn't install devDependencies during git-dep `prepare`.
-
-## Release pitfalls — do not repeat
-
-- **`--provenance` does NOT work for this package.** npm rejects provenance attestations for private source repos ("Only public source repositories are supported when publishing with provenance"). The workflow intentionally omits `--provenance` and `id-token: write`. Do not add them back.
-- **Tags are immutable.** If a publish fails, bump the version and push a new tag — never delete and re-push the same tag. Gaps in the npm version sequence are fine.
-- **Tag version must equal `package.json.version`.** The workflow fails fast if they disagree.
-- **Do not run `npm publish` locally.** The workflow is the canonical path.
-- **Never push `chore: release X.Y.Z` directly to main.** It still goes through a PR (rule 3).
-
-## Security note for contributors
-
-This package is published to npm as-is. Anything written into `skills/**`, `extensions/**`, or `agents.md` becomes public once published. **Never** embed tokens, API keys, passwords, internal-only URLs, customer names, or any non-public information in these files. Runtime configuration (credentials, per-user endpoints) must come from environment variables or user config — never hard-coded.
-
-The source repo `tplog/pi-zendy` is private by design. The `files` whitelist in `package.json` controls what ships to the public npm tarball. Do not propose making the repo public.

package/extensions/custom-header.ts

@@ -1,49 +0,0 @@
-/**
- * Custom Header Extension
- *
- * Displays "zendy" in ASCII art on startup.
- */
-
-import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
-
-function getZendyArt(theme: Theme): string[] {
-  const c = (text: string) => theme.fg("accent", text);
-  const d = (text: string) => theme.fg("dim", text);
-  const m = (text: string) => theme.fg("muted", text);
-
-  return [
-    "",
-    c("███████╗███████╗███╗   ██╗██████╗ ██╗   ██╗"),
-    c("╚══███╔╝██╔════╝████╗  ██║██╔══██╗╚██╗ ██╔╝"),
-    c("  ███╔╝ █████╗  ██╔██╗ ██║██║  ██║ ╚████╔╝"),
-    c(" ███╔╝  ██╔══╝  ██║╚██╗██║██║  ██║  ╚██╔╝"),
-    c("███████╗███████╗██║ ╚████║██████╔╝   ██║"),
-    c("╚══════╝╚══════╝╚═╝  ╚═══╝╚═════╝    ╚═╝"),
-    "",
-    m("─── ") + d("Dify Enterprise Copilot") + m(" ───"),
-    "",
-  ];
-}
-
-export default function (pi: ExtensionAPI) {
-  pi.on("session_start", async (_event, ctx) => {
-    if (ctx.hasUI) {
-      ctx.ui.setHeader((_tui, theme) => {
-        return {
-          render(_width: number): string[] {
-            return getZendyArt(theme);
-          },
-          invalidate() {},
-        };
-      });
-    }
-  });
-
-  pi.registerCommand("restore-header", {
-    description: "Restore built-in header",
-    handler: async (_args, ctx) => {
-      ctx.ui.setHeader(undefined);
-      ctx.ui.notify("Built-in header restored", "info");
-    },
-  });
-}