@elinpf/dsh-ops-tool-prometheus 0.2.0

package/README.i18n.yaml

@@ -0,0 +1,4 @@
+title: "@elinpf/dsh-ops-tool-prometheus"
+description:
+  zh: "运维模式 prometheus 工具 — 解析 prometheus 档案,直接对 Prometheus HTTP API 执行 PromQL 查询(instant/range),bearer token 自动注入"
+  en: "prometheus tool for ops mode — resolves prometheus profiles and runs PromQL instant/range queries over the Prometheus HTTP API, injecting the bearer token automatically"

package/README.md

@@ -0,0 +1,32 @@
+# @elinpf/dsh-ops-tool-prometheus
+
+The `prometheus` tool for DeepSeek Harness ops mode — resolves a named `prometheus` profile through the ops-access seam and runs a PromQL query directly against the Prometheus HTTP API (`/api/v1/query` / `/api/v1/query_range`), injecting the bearer token automatically. No shell, no curl heredocs.
+
+## What it does
+
+The model calls `prometheus` with a `cluster` (profile name) and a `query` (PromQL). With no time arguments it runs an instant query at now; `time` (RFC3339 or unix seconds) pins the instant; `start`+`end`+`step` (all three) make it a range query. The tool resolves the profile on every call (no caching — credential edits take effect immediately), reads the optional bearer-token file, sends the request with a 30 s timeout (`timeoutSec`, 1–600 s, overrides per call), and returns the suite-standard `{ exitCode, stdout, stderr, command, error? }` result.
+
+## Design notes
+
+- **HTTP, not shell.** The Prometheus API is a plain GET with URL-encoded parameters — routing it through `ctx.shell` + curl only added quoting bugs (the motivation for this tool: a real incident session hand-wrote ~15 curl heredocs, 5 of them broken). The result shape, output schema, and render duplicate the `@elinpf/dsh-ops-shell-tool` contract verbatim so the four consumer tools cannot drift apart.
+- **Failure taxonomy.** A PromQL rejection (`status: "error"` in the API envelope) is the server's answer: `exitCode: 1`, `errorType: error` on stderr. Transport failures — connection refused, timeout (`AbortSignal.timeout`), caller abort, non-Prometheus HTTP status — are `exitCode: -1` with the cause named in `error`, never a bare -1.
+- **No secret material in band.** The token travels only in the `Authorization` header, which is never logged or echoed; every returned string is additionally scrubbed against the token value defensively. The server URL is plain connection metadata and DOES appear in the displayed command (`prometheus <cluster> query='...' @ http://host:9090/api/v1/query`) so the agent can confirm which instance it hit. A token-file read failure is reported without its path — credential paths never reach the model.
+- **Size guards.** Range results are capped at 100 series (rest omitted with a note), 50 points per series (evenly sampled, first and last kept, noted in the series header), and ~100KB of stdout (cut with a truncation note pointing at narrower selectors / larger steps).
+- **Registration is an effect.** The tool registers via `ctx.effect(() => ctx.tools.register(...))`, so fiber disposal / HMR unloads it cleanly. The `./invariant` subpath registers a no-op invariant companion: the tool is stateless and owns no session events.
+
+## Configuration
+
+Schemastery schema, one option:
+
+| Key | Default | Meaning |
+|---|---|---|
+| `timeoutMs` | `30000` | Per-call HTTP timeout for Prometheus queries (ms). Slow queries may need more. |
+
+## Testing
+
+```sh
+npm run build     # tsc → lib/ (plugins load lib/, not src/)
+npx vitest run    # unit tests against a mock ctx + injected fake fetch — no network
+```
+
+The suite covers instant/range routing and URL encoding, argument-shape rejections (time vs start/end/step, partial range), bearer-token injection/scrubbing, the Prometheus/HTTP/network/timeout failure mapping, the series/points/bytes size guards, render purity, export shape (`.` / `./invariant` / `./types`), and HMR unload.

package/README.zh.md

@@ -0,0 +1,32 @@
+# @elinpf/dsh-ops-tool-prometheus
+
+DeepSeek Harness 运维模式下的 `prometheus` 工具 — 通过 ops-access 接缝按名字解析 `prometheus` 档案(profile),直接对 Prometheus HTTP API(`/api/v1/query` / `/api/v1/query_range`)执行 PromQL 查询,bearer token 自动注入。不走 shell,不写 curl heredoc。
+
+## 它做什么
+
+模型用 `cluster`(档案名)和 `query`(PromQL)调用 `prometheus` 工具。不带时间参数 = 当前时刻的 instant 查询;`time`(RFC3339 或 unix 秒)固定 instant 时刻;`start`+`end`+`step` 三个都给 = range 查询。工具每次调用都重新解析档案(不缓存,凭证改动立即生效),读取可选的 bearer-token 文件,以 30 秒超时发请求(`timeoutSec` 可单次覆盖,1–600 秒),返回套件标准结果 `{ exitCode, stdout, stderr, command, error? }`。
+
+## 设计要点
+
+- **走 HTTP,不走 shell。** Prometheus API 就是一次 URL 编码的 GET——经 `ctx.shell` + curl 只会引入引号 bug(本工具的动机:一次真实排查会话手写了约 15 次 curl heredoc,写错 5 次)。结果形态、输出 schema、render 逐字复刻 `@elinpf/dsh-ops-shell-tool` 的契约,保证消费工具不各自漂移。
+- **失败分级。** PromQL 被拒(API 信封里 `status: "error"`)是服务器的回答:`exitCode: 1`,stderr 放 `errorType: error`。传输层失败——连接被拒、超时(`AbortSignal.timeout`)、调用方中止、非 Prometheus 的 HTTP 状态——一律 `exitCode: -1`,`error` 写明首因,永不裸 -1。
+- **秘密不经过工具。** token 只出现在 `Authorization` 头里,永不进日志或回显;所有返回字符串额外按 token 值做防御性擦除。服务器 URL 是普通连接参数,会出现在展示命令里(`prometheus <cluster> query='...' @ http://host:9090/api/v1/query`),让 agent 能确认打到哪个实例。token 文件读取失败的报错不带路径——凭证路径永不进模型视野。
+- **大小护栏。** range 结果最多 100 个 series(超出省略并注明)、每 series 50 个点(均匀抽样、首尾必留、头部注明)、stdout ~100KB(截断并注明,指路更窄的选择器/更大的 step)。
+- **注册即 effect。** 工具经 `ctx.effect(() => ctx.tools.register(...))` 注册,fiber 销毁 / HMR 时干净卸载。`./invariant` 子路径注册一个空实现的 invariant 伴生插件:本工具无状态、不拥有 session 事件。
+
+## 配置项
+
+schemastery schema,仅一项:
+
+| 键 | 默认值 | 含义 |
+|---|---|---|
+| `timeoutMs` | `30000` | 单次 Prometheus 查询的 HTTP 超时(毫秒)。慢查询可调大。 |
+
+## 测试方式
+
+```sh
+npm run build     # tsc → lib/(插件加载的是 lib/,不是 src/)
+npx vitest run    # 基于 mock ctx + 注入的 fake fetch 的单元测试,不碰网络
+```
+
+测试覆盖:instant/range 路由与 URL 编码、参数形状拒绝(time 与 start/end/step 互斥、range 三缺一)、bearer token 注入与擦除、Prometheus/HTTP/网络/超时失败映射、series/点数/字节三级大小护栏、render 纯函数性、导出形态(`.` / `./invariant` / `./types` 三个入口)、以及 HMR 卸载。

package/cordis.patch.yml

@@ -0,0 +1 @@
+[]

package/lib/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Ops prometheus tool consumer.
+ *
+ * The `prometheus` tool: resolves a `prometheus` profile through the
+ * ops-access seam and runs a PromQL query directly against the Prometheus
+ * HTTP API (GET /api/v1/query or /api/v1/query_range) — no ctx.shell, no
+ * curl heredocs. When the profile carries a token fileField, the file is
+ * read per call and sent as `Authorization: Bearer`; the token itself never
+ * reaches the result, the displayed command, or any error text (every
+ * returned string is scrubbed against it defensively).
+ *
+ * The result shape `{ exitCode, stdout, stderr, command, error? }`, output
+ * schema, and render duplicate the ops-shell-tool contract verbatim — that
+ * factory wraps ctx.shell commands, which this tool is not, and it does not
+ * export the contract separately.
+ *
+ * @module @elinpf/dsh-ops-tool-prometheus
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { PrometheusToolConfig } from './types.js';
+export type { PrometheusToolConfig, PrometheusToolResult } from './types.js';
+export declare const name = "ops-tool-prometheus";
+export declare const inject: string[];
+export declare const Config: z<PrometheusToolConfig>;
+/** `up{instance="x",job="y"}` — the __name__ label leads, the rest sort-free. */
+export declare function metricToString(metric: Record<string, string>): string;
+/** Format a successful Prometheus response body by its resultType. */
+export declare function formatResult(data: {
+    resultType?: string;
+    result?: unknown;
+}): string;
+/** Cut stdout at ~100KB with an explicit note — never a silent truncation. */
+export declare function truncateStdout(text: string): string;
+/** Injectable fetch (tests); defaults to the global fetch. */
+export interface PrometheusToolDeps {
+    fetchFn?: typeof fetch;
+}
+export declare function createPrometheusTool(ctx: Context, config: PrometheusToolConfig, deps?: PrometheusToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition;
+export declare function apply(ctx: Context, config: PrometheusToolConfig): void;

package/lib/index.js

@@ -0,0 +1,281 @@
+/**
+ * Ops prometheus tool consumer.
+ *
+ * The `prometheus` tool: resolves a `prometheus` profile through the
+ * ops-access seam and runs a PromQL query directly against the Prometheus
+ * HTTP API (GET /api/v1/query or /api/v1/query_range) — no ctx.shell, no
+ * curl heredocs. When the profile carries a token fileField, the file is
+ * read per call and sent as `Authorization: Bearer`; the token itself never
+ * reaches the result, the displayed command, or any error text (every
+ * returned string is scrubbed against it defensively).
+ *
+ * The result shape `{ exitCode, stdout, stderr, command, error? }`, output
+ * schema, and render duplicate the ops-shell-tool contract verbatim — that
+ * factory wraps ctx.shell commands, which this tool is not, and it does not
+ * export the contract separately.
+ *
+ * @module @elinpf/dsh-ops-tool-prometheus
+ */
+import z from '@deepseek-ai/schemastery';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { readFile } from 'node:fs/promises';
+// ── Plugin identity ───────────────────────────────────────────────────────────
+export const name = 'ops-tool-prometheus';
+export const inject = ['tools'];
+// ── Config ───────────────────────────────────────────────────────────────────
+export const Config = z.object({
+    /** Per-call HTTP timeout for Prometheus queries (ms). Slow queries may need more. */
+    timeoutMs: z.number().default(30000),
+});
+// ── Output contract (verbatim copy of the ops-shell-tool one) ────────────────
+const output = {
+    schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            exitCode: { type: 'number', required: true },
+            stdout: { type: 'string', required: true },
+            stderr: { type: 'string', required: true },
+            command: { type: 'string', required: true },
+            error: { type: 'string' },
+        },
+    },
+    // Pure function of (args, value): same inputs, same text, no state touched.
+    render: (_args, value) => {
+        const parts = [];
+        if (value.command)
+            parts.push(`$ ${value.command}`);
+        if (value.stdout)
+            parts.push(value.stdout);
+        if (value.stderr)
+            parts.push(`[stderr]\n${value.stderr}`);
+        if (value.error)
+            parts.push(`[error] ${value.error}`);
+        if (value.exitCode !== 0 && value.exitCode !== undefined && value.exitCode !== null) {
+            parts.push(`[exit code: ${value.exitCode}]`);
+        }
+        return [{ type: 'text', text: parts.join('\n\n') || '(no output)' }];
+    },
+};
+// ── Formatting ───────────────────────────────────────────────────────────────
+/** Hard caps guarding the model's context against a fat range query. */
+const MAX_SERIES = 100;
+const MAX_POINTS_PER_SERIES = 50;
+/** ~100KB — stdout beyond this is cut and noted. */
+const MAX_STDOUT_CHARS = 100 * 1024;
+/** `up{instance="x",job="y"}` — the __name__ label leads, the rest sort-free. */
+export function metricToString(metric) {
+    const name = metric.__name__ ?? '';
+    const labels = Object.entries(metric)
+        .filter(([k]) => k !== '__name__')
+        .map(([k, v]) => `${k}="${v}"`)
+        .join(',');
+    if (labels === '')
+        return name || '{}';
+    return `${name}{${labels}}`;
+}
+/** Prometheus timestamps are unix seconds (possibly fractional). */
+function iso(ts) {
+    return new Date(ts * 1000).toISOString();
+}
+function formatVector(result) {
+    if (result.length === 0)
+        return 'empty result — the query matched no series at that time';
+    const shown = result.slice(0, MAX_SERIES);
+    const lines = shown.map((s) => `${metricToString(s.metric)} = ${s.value?.[1]} @ ${iso(s.value?.[0] ?? 0)}`);
+    if (result.length > shown.length) {
+        lines.push(`(+${result.length - shown.length} more series omitted — narrow the query with more label matchers)`);
+    }
+    return lines.join('\n');
+}
+function formatScalar(result) {
+    return `${result[1]} @ ${iso(result[0])}`;
+}
+/**
+ * Evenly sample `values` down to MAX_POINTS_PER_SERIES, always keeping the
+ * first and last point — the shape of a spike survives sampling.
+ */
+function samplePoints(values) {
+    if (values.length <= MAX_POINTS_PER_SERIES)
+        return { points: values, sampled: false };
+    const points = [];
+    for (let i = 0; i < MAX_POINTS_PER_SERIES; i++) {
+        points.push(values[Math.floor(i * (values.length - 1) / (MAX_POINTS_PER_SERIES - 1))]);
+    }
+    return { points, sampled: true };
+}
+function formatMatrix(result) {
+    if (result.length === 0)
+        return 'empty result — the query matched no series in that range';
+    const shown = result.slice(0, MAX_SERIES);
+    const blocks = shown.map((s) => {
+        const values = s.values ?? [];
+        const { points, sampled } = samplePoints(values);
+        const header = `${metricToString(s.metric)} — ${values.length} points${sampled ? `, showing ${points.length} evenly sampled` : ''}`;
+        return [header, ...points.map(([ts, v]) => `  ${iso(ts)}  ${v}`)].join('\n');
+    });
+    if (result.length > shown.length) {
+        blocks.push(`(+${result.length - shown.length} more series omitted — narrow the query with more label matchers)`);
+    }
+    return blocks.join('\n\n');
+}
+/** Format a successful Prometheus response body by its resultType. */
+export function formatResult(data) {
+    switch (data.resultType) {
+        case 'vector': return formatVector((data.result ?? []));
+        case 'matrix': return formatMatrix((data.result ?? []));
+        case 'scalar':
+        case 'string': return formatScalar(data.result);
+        default: return `unsupported resultType "${String(data.resultType)}" — raw result:\n${JSON.stringify(data.result ?? null, null, 2)}`;
+    }
+}
+/** Cut stdout at ~100KB with an explicit note — never a silent truncation. */
+export function truncateStdout(text) {
+    if (text.length <= MAX_STDOUT_CHARS)
+        return text;
+    return text.slice(0, MAX_STDOUT_CHARS)
+        + `\n... [truncated: the result exceeded ${Math.round(MAX_STDOUT_CHARS / 1024)}KB — narrow the query (more label matchers), shorten the range, or raise the step]`;
+}
+/** Single-quote a value for the display command (display only, never executed). */
+function quoteArg(value) {
+    return "'" + value.split("'").join("'\\''") + "'";
+}
+function errorMessage(e) {
+    return String(e?.message || e);
+}
+export function createPrometheusTool(ctx, config, deps = {}) {
+    const fetchFn = deps.fetchFn ?? fetch;
+    return defineTool({
+        name: 'prometheus',
+        description: 'Query a Prometheus server with PromQL over its HTTP API: an instant query (optionally at `time`), or a range query when start+end+step are all given. Resolves the server URL and optional bearer token from a registered `prometheus` profile (see list_access). The API is read-only. Prefer this over hand-rolled curl: credentials, encoding, and timeouts are handled.',
+        parameters: {
+            cluster: { type: 'string', required: true, description: 'Prometheus profile name (kind `prometheus`; a `prometheus/` prefix is tolerated). Use list_access to see options.' },
+            query: { type: 'string', required: true, description: 'The PromQL expression, e.g. `rate(http_requests_total{job="api"}[5m])`.' },
+            time: { type: 'string', description: 'Instant query evaluation time: RFC3339 or unix seconds. Defaults to now. Mutually exclusive with start/end/step.' },
+            start: { type: 'string', description: 'Range query start (RFC3339 or unix seconds). Requires end and step.' },
+            end: { type: 'string', description: 'Range query end (RFC3339 or unix seconds). Requires start and step.' },
+            step: { type: 'string', description: 'Range query resolution step, e.g. "15s", "1m". Requires start and end.' },
+            timeoutSec: { type: 'number', description: 'Optional per-call timeout in seconds (default 30, max 600). Use only for a query you KNOW is slow (a wide range over many series) — a longer wait does not fix an unreachable server.' },
+        },
+        output,
+        async execute(args, exec) {
+            const cluster = args.cluster;
+            const query = args.query;
+            const time = args.time;
+            const start = args.start;
+            const end = args.end;
+            const step = args.step;
+            const fail = (message, command = '') => ({ error: message, exitCode: -1, stdout: '', stderr: message, command });
+            // Argument shape first — cheap, side-effect free, and the teaching
+            // message is most useful BEFORE a credential resolve has happened.
+            const rangeArgs = [start, end, step].filter((v) => v !== undefined).length;
+            if (time !== undefined && rangeArgs > 0) {
+                return fail('time is mutually exclusive with start/end/step — an instant query uses time (or neither, for now); a range query uses start+end+step');
+            }
+            if (rangeArgs > 0 && rangeArgs < 3) {
+                return fail('a range query needs ALL of start, end and step (e.g. step "15s") — got only ' + rangeArgs + ' of them');
+            }
+            const isRange = rangeArgs === 3;
+            const display = `prometheus ${cluster} query=${quoteArg(query)}`
+                + (time !== undefined ? ` time=${time}` : '')
+                + (isRange ? ` start=${start} end=${end} step=${step}` : '');
+            let token;
+            /** Defensive: the token must never reach model-visible output. */
+            const scrub = (text) => token !== undefined && token.length >= 8 ? text.split(token).join('<token>') : text;
+            let command = display;
+            try {
+                // Resolve the seam per call through ctx.get — never a static inject,
+                // never cached. Same discipline as the shell-tool factory.
+                const opsAccess = ctx.get('opsAccess');
+                if (!opsAccess) {
+                    return fail('ops-access service unavailable — is the ops-access plugin mounted in this preset?', display);
+                }
+                // Pass the caller agent through so the access gate (if mounted) can
+                // key grants on the session id. Core tolerates a `prometheus/` prefix
+                // on the name.
+                const profile = await opsAccess.resolve('prometheus', cluster, exec.agent);
+                const baseUrl = String(profile.fields.url ?? '');
+                const endpoint = isRange ? '/api/v1/query_range' : '/api/v1/query';
+                command = `${display} @ ${baseUrl}${endpoint}`;
+                // The token field is a PATH to a managed file (fileField). A read
+                // failure is reported without the path — credential paths never
+                // reach the model (same discipline as the shell-tool's ref tokens).
+                if (typeof profile.fields.token === 'string' && profile.fields.token !== '') {
+                    try {
+                        token = (await readFile(profile.fields.token, 'utf8')).trim();
+                    }
+                    catch {
+                        return fail(`the bearer token file of profile "${profile.name}" could not be read — re-register the token via register_access or the admin UI`, command);
+                    }
+                }
+                const u = new URL(baseUrl + endpoint);
+                u.searchParams.set('query', query);
+                if (isRange) {
+                    u.searchParams.set('start', start);
+                    u.searchParams.set('end', end);
+                    u.searchParams.set('step', step);
+                }
+                else if (time !== undefined) {
+                    u.searchParams.set('time', time);
+                }
+                let timeoutMs = config.timeoutMs;
+                const override = args.timeoutSec;
+                if (typeof override === 'number' && Number.isFinite(override) && override >= 1 && override <= 600) {
+                    timeoutMs = Math.round(override * 1000);
+                }
+                const signals = [AbortSignal.timeout(timeoutMs)];
+                if (exec.signal)
+                    signals.push(exec.signal);
+                // Headers carry the token; they are never logged or echoed — only
+                // the URL (plain connection metadata) appears in `command`.
+                const headers = token !== undefined ? { authorization: `Bearer ${token}` } : {};
+                const response = await fetchFn(u.toString(), { headers, signal: AbortSignal.any(signals) });
+                const text = await response.text();
+                let body;
+                try {
+                    body = JSON.parse(text);
+                }
+                catch {
+                    body = undefined;
+                }
+                // A PromQL rejection arrives as status:'error' (usually with HTTP
+                // 4xx) — that is the SERVER's answer, so it is exitCode 1, not -1.
+                if (body?.status === 'error') {
+                    const detail = `${body.errorType ?? 'error'}: ${body.error ?? 'unknown error'}`;
+                    return { exitCode: 1, stdout: '', stderr: scrub(detail), command, error: scrub(detail) };
+                }
+                if (!response.ok) {
+                    const message = `the Prometheus server answered HTTP ${response.status} ${response.statusText}`.trimEnd();
+                    return { ...fail(scrub(message), command), stderr: scrub(text.slice(0, 2000)) };
+                }
+                if (body?.status !== 'success') {
+                    return fail(scrub(`unexpected response from the Prometheus server (not a prometheus API envelope, ${text.length} bytes) — is ${baseUrl} really a Prometheus?`), command);
+                }
+                const stdout = truncateStdout(scrub(formatResult(body.data ?? {})));
+                const stderr = (body.warnings ?? []).map((w) => `warning: ${scrub(w)}`).join('\n');
+                return { exitCode: 0, stdout, stderr, command };
+            }
+            catch (e) {
+                const err = e;
+                let message;
+                if (err.name === 'TimeoutError') {
+                    message = `timed out — the Prometheus server did not answer within the tool timeout. For a known-slow query pass timeoutSec (max 600); for a wide range query raise the step or narrow the selector instead`;
+                }
+                else if (err.name === 'AbortError') {
+                    message = 'aborted: the caller cancelled this query before it finished.';
+                }
+                else {
+                    // fetch network failures (TypeError 'fetch failed' + cause) — the
+                    // message carries no headers, and the URL is not secret.
+                    const cause = err.cause?.message ? ` (${err.cause.message})` : '';
+                    message = `connection to the Prometheus server failed: ${errorMessage(e)}${cause}`;
+                }
+                return fail(scrub(message), command);
+            }
+        },
+    });
+}
+// ── Plugin apply ─────────────────────────────────────────────────────────────
+export function apply(ctx, config) {
+    ctx.effect(() => ctx.tools.register(createPrometheusTool(ctx, config)));
+}

package/lib/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Invariant companion for @elinpf/dsh-ops-tool-prometheus.
+ *
+ * @module @elinpf/dsh-ops-tool-prometheus/invariant
+ */
+/** Cordis companion plugin name. */
+declare const name = "ops-prometheus-invariant";
+/** Service required before the companion can reserve package ownership. */
+declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Context carrying the invariant service.
+ * @returns a promise resolving after registration.
+ */
+declare const apply: (ctx: any) => Promise<void>;
+export { apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,26 @@
+/**
+ * Invariant companion for @elinpf/dsh-ops-tool-prometheus.
+ *
+ * @module @elinpf/dsh-ops-tool-prometheus/invariant
+ */
+const PACKAGE_NAME = '@elinpf/dsh-ops-tool-prometheus';
+/** Cordis companion plugin name. */
+const name = 'ops-prometheus-invariant';
+/** Service required before the companion can reserve package ownership. */
+const inject = ['invariants'];
+/**
+ * No runtime invariant: this tool is stateless. It owns no session events and
+ * no durable shape — every call re-resolves the credential profile through
+ * the ops-access seam and runs one HTTP query, so there is nothing to fold
+ * and nothing to check.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Context carrying the invariant service.
+ * @returns a promise resolving after registration.
+ */
+const apply = async (ctx) => {
+    ctx.invariants.register(PACKAGE_NAME, install);
+};
+export { apply, inject, name };

package/lib/types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Type definitions for the ops-tool-prometheus plugin.
+ *
+ * Types only — no runtime values live here (not even consts), so importing
+ * this module never pulls in plugin code.
+ *
+ * @module @elinpf/dsh-ops-tool-prometheus
+ */
+/**
+ * Resolved configuration of the ops-tool-prometheus plugin (post-schema defaults).
+ */
+export interface PrometheusToolConfig {
+    /** Per-call HTTP timeout for Prometheus queries (ms). Slow queries may need more. */
+    timeoutMs: number;
+}
+/**
+ * The suite-standard tool result shape — identical to ShellToolResult in
+ * @elinpf/dsh-ops-shell-tool. Duplicated here (with the output schema/render)
+ * because this tool speaks HTTP, not shell: it does not go through
+ * registerProfiledShellTool, and ops-shell-tool does not export the contract
+ * separately.
+ */
+export interface PrometheusToolResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    command: string;
+    error?: string;
+}

package/lib/types.js

@@ -0,0 +1,9 @@
+/**
+ * Type definitions for the ops-tool-prometheus plugin.
+ *
+ * Types only — no runtime values live here (not even consts), so importing
+ * this module never pulls in plugin code.
+ *
+ * @module @elinpf/dsh-ops-tool-prometheus
+ */
+export {};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@elinpf/dsh-ops-tool-prometheus",
+  "version": "0.2.0",
+  "description": "prometheus tool consumer of the ops-access seam — resolves prometheus profiles and runs PromQL instant/range queries over the Prometheus HTTP API, injecting the bearer token automatically.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./types": {
+      "types": "./lib/types.d.ts",
+      "default": "./lib/types.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types.js",
+    "lib/**/*.d.ts",
+    "cordis.patch.yml"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.8",
+    "@elinpf/dsh-ops-access": "^0.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-tools": "0.0.1-rc.1",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.11",
+    "@elinpf/dsh-ops-access": "0.2.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}