@bytesbrains/pi-loki-gate 1.0.0

package/AGENTS.md

@@ -0,0 +1,84 @@
+# Loki Gate — Agent Usage Guide
+
+> You are an AI agent. Use loki-gate tools to query structured logs from Grafana Loki.
+> For complete raw container output (including console.log), use docker-logs tools.
+
+## Quickstart
+
+```bash
+loki_query(query='{service_name="worker"}')                        # Raw LogQL query
+loki_job_logs(jobId="af57818e")                                    # Logs for a specific job
+loki_worker_logs(worker="1")                                       # Logs from workers
+```
+
+## Available Labels
+
+Loki in wrok.in uses these labels:
+
+| Label | Values | Description |
+|-------|--------|-------------|
+| `service_name` | `worker`, `orchestrator`, `unknown` | Which service produced the log |
+| `service` | `worker`, `orchestrator`, `unknown` | Same as service_name |
+| `agent` | `developer`, `code-reviewer`, etc. | Which agent was running |
+
+No per-container labels exist — use `docker_worker_logs` for per-container granularity.
+
+## Tools
+
+### loki_query
+
+Run an arbitrary LogQL query against Loki. Best for exploring structured application logs.
+
+```bash
+loki_query(query='{service_name="orchestrator"}')
+loki_query(query='{service_name="worker"} |= "error"')
+loki_query(query='{service_name="worker",agent="developer"}', limit=50)
+```
+
+### loki_job_logs
+
+Fetch log lines containing a specific factory job ID. Searches across worker and orchestrator logs.
+
+> **Note:** Only finds jobs in structured JSON log lines. Console output ("Job X complete") is only in Docker logs. Use `docker_worker_logs` or `docker_container_logs` for complete job output.
+
+```bash
+loki_job_logs(jobId="af57818e")
+loki_job_logs(jobId="e81f04e9", limit=500)
+```
+
+### loki_worker_logs
+
+Fetch logs from workers or orchestrator via Loki. Filters by `service_name`.
+
+```bash
+loki_worker_logs(worker="1")
+loki_worker_logs(worker="3", search="error")
+loki_worker_logs(container="ai-factory-orchestrator", search="dispatch")
+```
+
+## Configuration
+
+`.lokirc.yml`:
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `lokiUrl` | `http://localhost:3100` | Grafana Loki API URL |
+| `defaultLimit` | `100` | Default log lines per query |
+
+## Loki vs Docker
+
+| | Loki (`loki_*`) | Docker (`docker_*`) |
+|---|---|---|
+| **Captures** | Structured JSON logs only | All stdout/stderr (console.log + JSON) |
+| **Filtering** | Label-based (agent, service) | Text search (`search` param) |
+| **Per-container** | ❌ No container_name label | ✅ Exact container targeting |
+| **Best for** | Exploring by service/agent, error aggregation | Complete job/worker output, console messages |
+| **Requires** | Loki running (port 3100) | Docker CLI + socket access |
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| `loki_query()` returns nothing | Verify Loki is running: `curl http://localhost:3100/ready` |
+| Labels wrong | Available: `agent`, `service`, `service_name`. Check: `curl http://localhost:3100/loki/api/v1/labels` |
+| Job logs empty | Job ID is likely in console.log, not structured JSON. Use `docker_worker_logs` instead. |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nandal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# pi-loki-gate
+
+Loki log gateway for pi agents — query Grafana Loki for structured application logs from the [wrok.in](https://github.com/nandal/wrok.in) AI Factory.
+
+For raw Docker container output (console.log + everything), use [pi-docker-logs](../docker-logs).
+
+## Install
+
+```bash
+pi install npm:pi-loki-gate
+```
+
+## Configuration
+
+Add a `.lokirc.yml` to your repo root:
+
+```yaml
+lokiUrl: http://localhost:3100
+defaultLimit: 100
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `lokiUrl` | `http://localhost:3100` | Grafana Loki API URL |
+| `defaultLimit` | `100` | Default log lines per query |
+
+## Available Labels
+
+| Label | Values | Description |
+|-------|--------|-------------|
+| `service_name` | `worker`, `orchestrator` | Service producing the log |
+| `service` | `worker`, `orchestrator` | Same as service_name |
+| `agent` | `developer`, etc. | Agent running the task |
+
+## Tools
+
+### loki_query
+
+Run arbitrary LogQL queries against Loki.
+
+```
+loki_query(query='{service_name="orchestrator"}')
+loki_query(query='{service_name="worker"} |= "error"', limit=50)
+```
+
+### loki_job_logs
+
+Fetch logs for a specific factory job by its ID.
+
+> **Note:** Only matches structured JSON log lines. Console output like "Job X complete" is only in Docker logs — use `docker_worker_logs` for full output.
+
+```
+loki_job_logs(jobId="af57818e")
+```
+
+### loki_worker_logs
+
+Fetch logs from workers or orchestrator via Loki.
+
+```
+loki_worker_logs(worker="1")
+loki_worker_logs(worker="3", search="error")
+loki_worker_logs(container="ai-factory-orchestrator")
+```
+
+## Loki vs Docker Logs
+
+| | Loki | Docker Logs |
+|---|---|---|
+| Captures | Structured JSON only | All stdout/stderr |
+| Per-container | ❌ | ✅ |
+| Label filtering | ✅ (agent, service) | ❌ (text search) |
+| Best for | Service/agent exploration, error patterns | Complete job output, console messages |
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@bytesbrains/pi-loki-gate",
+  "version": "1.0.0",
+  "description": "Loki log gateway for pi agents — query Grafana Loki for container/job/worker logs from the wrok.in AI Factory.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "loki",
+    "grafana",
+    "logs",
+    "logging",
+    "ai-factory"
+  ],
+  "author": "nandal <nandal@users.noreply.github.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nandal/pi-ext.git",
+    "directory": "loki-gate"
+  },
+  "homepage": "https://github.com/nandal/pi-ext/tree/main/loki-gate",
+  "bugs": {
+    "url": "https://github.com/nandal/pi-ext/issues"
+  },
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "AGENTS.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "vitest": "^2.1.9"
+  }
+}

package/src/config.ts

@@ -0,0 +1,29 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { LokiConfig } from "./types";
+import { DEFAULT_CONFIG } from "./types";
+
+export function loadConfig(cwd: string): LokiConfig {
+  const configPath = path.join(cwd, ".lokirc.yml");
+  if (!fs.existsSync(configPath)) return { ...DEFAULT_CONFIG };
+  try {
+    const content = fs.readFileSync(configPath, "utf-8");
+    const result: Record<string, unknown> = {};
+    for (const line of content.split("\n")) {
+      const m = line.match(/^\s*(\w[\w.]*):\s*(.+)$/);
+      if (m) {
+        let val = m[2].trim();
+        if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+          val = val.slice(1, -1);
+        }
+        result[m[1]] = val;
+      }
+    }
+    return {
+      lokiUrl: (result["lokiUrl"] as string) || DEFAULT_CONFIG.lokiUrl,
+      defaultLimit: parseInt(result["defaultLimit"] as string) || DEFAULT_CONFIG.defaultLimit,
+    };
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}

package/src/helpers.ts

@@ -0,0 +1,98 @@
+import type { LokiConfig, LokiQueryResult, LokiLogEntry } from "./types";
+
+/**
+ * Query Loki for log entries using LogQL.
+ */
+export async function lokiQuery(
+  config: LokiConfig,
+  query: string,
+  limit: number = config.defaultLimit,
+  direction: "forward" | "backward" = "backward",
+): Promise<{ ok: boolean; entries?: LokiLogEntry[]; error?: string; query: string }> {
+  const url = `${config.lokiUrl.replace(/\/$/, "")}/loki/api/v1/query_range`;
+  const nowNs = String(Date.now() * 1_000_000);
+  const oneHourAgoNs = String((Date.now() - 3600 * 1000) * 1_000_000);
+
+  const params = new URLSearchParams({
+    query,
+    start: oneHourAgoNs,
+    end: nowNs,
+    limit: String(limit),
+    direction,
+  });
+
+  try {
+    const res = await fetch(`${url}?${params}`, {
+      headers: { Accept: "application/json" },
+    });
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      return { ok: false, error: `Loki returned ${res.status}: ${text.slice(0, 200)}`, query };
+    }
+
+    const data = (await res.json()) as LokiQueryResult;
+
+    if (data.status !== "success") {
+      return { ok: false, error: `Loki query failed: ${JSON.stringify(data).slice(0, 200)}`, query };
+    }
+
+    const entries: LokiLogEntry[] = [];
+    for (const stream of data.data.result) {
+      for (const [tsNs, line] of stream.values) {
+        const ts = new Date(parseInt(tsNs) / 1_000_000).toISOString();
+        entries.push({ timestamp: ts, line, labels: stream.stream });
+      }
+    }
+
+    // Sort by timestamp
+    entries.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+
+    return { ok: true, entries, query };
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: msg, query };
+  }
+}
+
+/**
+ * Format a single log entry for display.
+ */
+export function formatLogEntry(entry: LokiLogEntry, showLabels: boolean = false): string {
+  const ts = entry.timestamp.slice(0, 19).replace("T", " ");
+  const container = entry.labels.service_name || entry.labels.service || "";
+  const prefix = container ? `${ts} [${container}]` : ts;
+  if (showLabels) {
+    const labelStr = Object.entries(entry.labels)
+      .map(([k, v]) => `${k}=${v}`)
+      .join(", ");
+    return `${prefix} ${entry.line}  # ${labelStr}`;
+  }
+  return `${prefix} ${entry.line}`;
+}
+
+/**
+ * Format log entries with truncation for display.
+ */
+export function formatLogOutput(
+  entries: LokiLogEntry[],
+  maxLines: number,
+  showLabels: boolean = false,
+): string {
+  if (entries.length === 0) return "No log entries found.";
+
+  const total = entries.length;
+  const truncated = total > maxLines;
+
+  let output = entries
+    .slice(truncated ? total - maxLines : 0)
+    .map((e) => formatLogEntry(e, showLabels))
+    .join("\n");
+
+  if (truncated) {
+    output = `... [${total - maxLines} lines truncated] ...\n${output}`;
+  }
+
+  output = `📋 ${total} log entries${truncated ? ` (showing last ${maxLines})` : ""}\n\n${output}`;
+  return output;
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * pi-loki-gate — Loki Log Gateway
+ *
+ * Tools: loki_query, loki_job_logs, loki_worker_logs
+ * Config: .lokirc.yml
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { queryLogsTool, jobLogsTool, workerLogsTool } from "./tools/query";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool(queryLogsTool);
+  pi.registerTool(jobLogsTool);
+  pi.registerTool(workerLogsTool);
+}

package/src/tools/query.ts

@@ -0,0 +1,179 @@
+import { Type } from "typebox";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../config";
+import { lokiQuery, formatLogOutput } from "../helpers";
+
+// ─── Query Logs ───────────────────────────────────────────────────────────────
+
+export const queryLogsTool = {
+  name: "loki_query" as const,
+  label: "Query Loki Logs",
+  description:
+    "Run a LogQL query against the Grafana Loki log aggregator. Returns matching log entries with timestamps and container labels. Available labels: service_name (worker|orchestrator), service, agent. Use for free-form log exploration.",
+  parameters: Type.Object({
+    query: Type.String({
+      description:
+        'LogQL query string (e.g. \'{service_name="worker"}\', \'{service_name="orchestrator"} |= "error"\', etc.)',
+    }),
+    limit: Type.Optional(Type.Number({ description: "Max log lines to return (default: 100)" })),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const config = loadConfig(ctx.cwd);
+    const limit = params.limit || config.defaultLimit;
+
+    const result = await lokiQuery(config, params.query, limit);
+
+    if (!result.ok) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `❌ Loki query failed: ${result.error}\n   Query: ${result.query}`,
+          },
+        ],
+        isError: true,
+        details: { query: result.query },
+      };
+    }
+
+    const entries = result.entries!;
+    const output = formatLogOutput(entries, limit, true);
+
+    return {
+      content: [{ type: "text", text: output }],
+      details: { query: result.query, count: entries.length },
+    };
+  },
+};
+
+// ─── Job Logs ──────────────────────────────────────────────────────────────────
+
+export const jobLogsTool = {
+  name: "loki_job_logs" as const,
+  label: "Get Job Logs from Loki",
+  description:
+    "Fetch logs for a specific wrok.in factory job by searching for its job ID across worker and orchestrator logs. Matches log lines containing the job ID.",
+  parameters: Type.Object({
+    jobId: Type.String({ description: "Factory job ID (e.g. 'af57818e')" }),
+    limit: Type.Optional(Type.Number({ description: "Max log lines (default: 200)" })),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const config = loadConfig(ctx.cwd);
+    const limit = params.limit || 200;
+    const query = `{service_name=~"worker|orchestrator"} |= \`${params.jobId}\``;
+
+    const result = await lokiQuery(config, query, limit);
+
+    if (!result.ok) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `❌ Failed to get job logs: ${result.error}\n   Job: ${params.jobId}`,
+          },
+        ],
+        isError: true,
+        details: { jobId: params.jobId },
+      };
+    }
+
+    const entries = result.entries!;
+    if (entries.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `No log entries found for job "${params.jobId}".\n\nTry loki_query() with a broader query, or check if Loki is receiving logs.`,
+          },
+        ],
+        details: { jobId: params.jobId, count: 0 },
+      };
+    }
+
+    const output = formatLogOutput(entries, limit, false);
+
+    return {
+      content: [{ type: "text", text: output }],
+      details: { jobId: params.jobId, count: entries.length },
+    };
+  },
+};
+
+// ─── Worker Logs ───────────────────────────────────────────────────────────────
+
+export const workerLogsTool = {
+  name: "loki_worker_logs" as const,
+  label: "Get Worker Logs from Loki",
+  description:
+    "Fetch logs from a worker container via Loki. Filters by service_name (worker/orchestrator) and agent. Use docker_worker_logs for per-container granularity.",
+  parameters: Type.Object({
+    worker: Type.Optional(
+      Type.String({
+        description: 'Worker number or name (e.g. "1", "worker-1"). Filters to service_name="worker".',
+      }),
+    ),
+    container: Type.Optional(
+      Type.String({
+        description: "Container name (e.g. 'ai-factory-worker-1', 'ai-factory-orchestrator'). Maps to service_name filter.",
+      }),
+    ),
+    search: Type.Optional(Type.String({ description: "Text to search for in log lines" })),
+    limit: Type.Optional(Type.Number({ description: "Max log lines (default: 100)" })),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const config = loadConfig(ctx.cwd);
+    const limit = params.limit || config.defaultLimit;
+
+    // Build service filter (Loki labels: service_name=worker|orchestrator)
+    let serviceFilter = `service_name=~"worker|orchestrator"`;
+    if (params.container) {
+      if (params.container.includes("orchestrator")) {
+        serviceFilter = `service_name="orchestrator"`;
+      } else if (params.container.includes("worker")) {
+        serviceFilter = `service_name="worker"`;
+      }
+    } else if (params.worker) {
+      serviceFilter = `service_name="worker"`;
+    }
+
+    let query = `{${serviceFilter}}`;
+    if (params.search) {
+      query += ` |= \`${params.search}\``;
+    }
+
+    const result = await lokiQuery(config, query, limit);
+
+    if (!result.ok) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `❌ Failed to get worker logs: ${result.error}\n   Query: ${query}`,
+          },
+        ],
+        isError: true,
+        details: { query },
+      };
+    }
+
+    const entries = result.entries!;
+    if (entries.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `No log entries found for the specified worker.\n   Query: ${query}`,
+          },
+        ],
+        details: { query, count: 0 },
+      };
+    }
+
+    const output = formatLogOutput(entries, limit, false);
+
+    return {
+      content: [{ type: "text", text: output }],
+      details: { query, count: entries.length },
+    };
+  },
+};

package/src/types.ts

@@ -0,0 +1,36 @@
+/**
+ * pi-loki-gate — Types
+ */
+
+export interface LokiConfig {
+  /** Base URL of the Loki instance (e.g. http://localhost:3100) */
+  lokiUrl: string;
+  /** Default line limit for queries */
+  defaultLimit: number;
+}
+
+export const DEFAULT_CONFIG: LokiConfig = {
+  lokiUrl: "http://localhost:3100",
+  defaultLimit: 100,
+};
+
+// ── Loki API Types ──
+
+export interface LokiQueryResult {
+  status: string;
+  data: {
+    resultType: string;
+    result: LokiStream[];
+  };
+}
+
+export interface LokiStream {
+  stream: Record<string, string>;
+  values: Array<[string, string]>; // [timestamp_ns, log_line]
+}
+
+export interface LokiLogEntry {
+  timestamp: string; // ISO 8601
+  line: string;
+  labels: Record<string, string>;
+}