@bytesbrains/pi-docker-logs 1.0.0

package/AGENTS.md

@@ -0,0 +1,72 @@
+# Docker Logs — Agent Usage Guide
+
+> You are an AI agent. Use docker-logs tools to fetch complete raw logs from Docker containers.
+> For label-filtered structured logs, use loki-gate tools.
+
+## Quickstart
+
+```bash
+docker_container_list()                                           # See running containers
+docker_worker_logs(worker="1")                                    # Tail worker 1 logs
+docker_container_logs(container="ai-factory-orchestrator")        # Tail any container
+```
+
+## Tools
+
+### docker_container_list
+
+List running factory containers with type indicators.
+
+```bash
+docker_container_list()
+```
+
+### docker_worker_logs
+
+Fetch complete logs from a worker container. Resolves worker numbers (1-4, "worker-2") to container names automatically. Captures **all** output including `console.log` and structured JSON.
+
+```bash
+docker_worker_logs(worker="1")
+docker_worker_logs(worker="2", tail=500, search="error")
+docker_worker_logs(worker="3", since="30m")
+docker_worker_logs(worker="4", search="complete")
+```
+
+### docker_container_logs
+
+Fetch complete logs from any Docker container by name. Use for orchestrator, Gitea, Postgres, or any container.
+
+```bash
+docker_container_logs(container="ai-factory-orchestrator")
+docker_container_logs(container="ai-factory-gitea", tail=100)
+docker_container_logs(container="ai-factory-worker-1", search="exit=")
+docker_container_logs(container="ai-factory-postgres", since="1h")
+```
+
+## Docker vs Loki
+
+| | Docker (`docker_*`) | Loki (`loki_*`) |
+|---|---|---|
+| **Captures** | All stdout/stderr (console.log + JSON) | Structured JSON logs only |
+| **Per-container** | ✅ Exact container targeting | ❌ No container_name label |
+| **Label filtering** | ❌ Text search only (`search` param) | ✅ Filter by agent, service |
+| **Best for** | Complete job/worker output, console messages | Exploring by service/agent, error aggregation |
+| **Requires** | Docker CLI + socket access | Loki running (port 3100) |
+
+## Configuration
+
+`.dockerlogs.yml`:
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `tail` | `200` | Default number of log lines to tail |
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| `docker_container_list()` fails | Docker daemon may not be running. Run `docker ps` manually. |
+| Container not found | Use `docker_container_list()` to see exact names. |
+| Empty logs | Try increasing `tail` or using `since` to widen the window. |
+| Permission denied | Ensure current user has Docker access (`docker ps` works). |
+| Need label filtering | For agent/service filtering, use `loki_query` or `loki_worker_logs`. |

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,71 @@
+# pi-docker-logs
+
+Docker log gateway for pi agents — tail complete raw logs from Docker containers using the `docker` CLI. Works with the [wrok.in](https://github.com/nandal/wrok.in) AI Factory.
+
+For label-filtered structured logs (by agent/service), use [pi-loki-gate](../loki-gate).
+
+## Install
+
+```bash
+pi install npm:pi-docker-logs
+```
+
+## Configuration
+
+Add a `.dockerlogs.yml` to your repo root:
+
+```yaml
+tail: 200
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `tail` | `200` | Default number of log lines to tail |
+
+## Tools
+
+### docker_container_list
+
+List running factory containers.
+
+```
+docker_container_list()
+```
+
+### docker_worker_logs
+
+Fetch complete logs from a factory worker container. Captures all output (console.log + structured JSON).
+
+```
+docker_worker_logs(worker="1")
+docker_worker_logs(worker="2", tail=500, search="error")
+docker_worker_logs(worker="3", since="30m")
+```
+
+### docker_container_logs
+
+Fetch complete logs from any Docker container.
+
+```
+docker_container_logs(container="ai-factory-orchestrator")
+docker_container_logs(container="ai-factory-worker-1", search="exit=")
+docker_container_logs(container="ai-factory-gitea", tail=100, since="1h")
+```
+
+## Docker vs Loki Logs
+
+| | Docker Logs | Loki |
+|---|---|---|
+| Captures | All stdout/stderr | Structured JSON only |
+| Per-container | ✅ | ❌ |
+| Label filtering | ❌ (text search) | ✅ (agent, service) |
+| Best for | Complete job output, console messages | Service/agent exploration, error patterns |
+
+## Requirements
+
+- Docker CLI (`docker`) must be installed and on PATH
+- Current user must have Docker socket access
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@bytesbrains/pi-docker-logs",
+  "version": "1.0.0",
+  "description": "Docker log gateway for pi agents — tail logs from Docker containers in the wrok.in AI Factory via the docker CLI.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "docker",
+    "logs",
+    "logging",
+    "ai-factory"
+  ],
+  "author": "nandal <nandal@users.noreply.github.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nandal/pi-ext.git",
+    "directory": "docker-logs"
+  },
+  "homepage": "https://github.com/nandal/pi-ext/tree/main/docker-logs",
+  "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,28 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { DockerLogsConfig } from "./types";
+import { DEFAULT_CONFIG } from "./types";
+
+export function loadConfig(cwd: string): DockerLogsConfig {
+  const configPath = path.join(cwd, ".dockerlogs.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 {
+      tail: parseInt(result["tail"] as string) || DEFAULT_CONFIG.tail,
+    };
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}

package/src/helpers.ts

@@ -0,0 +1,118 @@
+import { execFile } from "node:child_process";
+import type { DockerLogsConfig } from "./types";
+
+// Known factory container names
+const FACTORY_CONTAINERS = [
+  "ai-factory-orchestrator",
+  "ai-factory-worker-1",
+  "ai-factory-worker-2",
+  "ai-factory-worker-3",
+  "ai-factory-worker-4",
+  "ai-factory-gitea",
+  "ai-factory-postgres",
+  "ai-factory-loki",
+  "ai-factory-grafana",
+];
+
+/**
+ * Run `docker logs` for a container and return stdout.
+ */
+export function dockerLogs(
+  container: string,
+  tail: number,
+  since?: string,
+): Promise<{ ok: boolean; text?: string; error?: string }> {
+  return new Promise((resolve) => {
+    const args = ["logs", "--timestamps"];
+    if (tail > 0) args.push("--tail", String(tail));
+    if (since) args.push("--since", since);
+    args.push(container);
+
+    execFile("docker", args, { timeout: 15000, maxBuffer: 2 * 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err) {
+        resolve({ ok: false, error: stderr || err.message });
+        return;
+      }
+      resolve({ ok: true, text: stdout });
+    });
+  });
+}
+
+/**
+ * List running Docker containers (factory-related).
+ */
+export function listContainers(): Promise<{ ok: boolean; containers?: string[]; error?: string }> {
+  return new Promise((resolve) => {
+    execFile(
+      "docker",
+      ["ps", "--format", "{{.Names}}", "--filter", "name=ai-factory"],
+      { timeout: 5000 },
+      (err, stdout, stderr) => {
+        if (err) {
+          resolve({ ok: false, error: stderr || err.message });
+          return;
+        }
+        const containers = stdout
+          .split("\n")
+          .map((c) => c.trim())
+          .filter(Boolean);
+        resolve({ ok: true, containers });
+      },
+    );
+  });
+}
+
+/**
+ * Resolve a worker spec to a container name.
+ */
+export function resolveWorkerContainer(spec: string): string | null {
+  // Already a full container name
+  if (spec.startsWith("ai-factory-")) return spec;
+  // Number or "worker-N"
+  const num = spec.replace(/^worker-/, "");
+  return `ai-factory-worker-${num}`;
+}
+
+/**
+ * Search log text for a pattern and return matching lines.
+ */
+export function grepLogs(text: string, pattern: string, contextLines: number = 0): string {
+  const lines = text.split("\n");
+  const matched: string[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].toLowerCase().includes(pattern.toLowerCase())) {
+      if (contextLines > 0) {
+        const start = Math.max(0, i - contextLines);
+        const end = Math.min(lines.length, i + contextLines + 1);
+        if (matched.length > 0 && start <= i - contextLines + 1) {
+          // Merge overlapping ranges
+          while (matched.length > 0) matched.pop();
+        }
+        for (let j = start; j < end; j++) {
+          matched.push(lines[j]);
+        }
+      } else {
+        matched.push(lines[i]);
+      }
+    }
+  }
+  return matched.join("\n");
+}
+
+/**
+ * Truncate log output for display.
+ */
+export function truncateOutput(text: string, maxLines: number): { text: string; truncated: boolean; totalLines: number } {
+  const lines = text.split("\n").filter(Boolean);
+  const totalLines = lines.length;
+  if (totalLines <= maxLines) return { text, truncated: false, totalLines };
+
+  const head = Math.ceil(maxLines * 0.2);
+  const tail = maxLines - head;
+  const truncated =
+    lines.slice(0, head).join("\n") +
+    `\n\n... [${totalLines - maxLines} lines truncated] ...\n\n` +
+    lines.slice(-tail).join("\n");
+
+  return { text: truncated, truncated: true, totalLines };
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * pi-docker-logs — Docker Log Gateway
+ *
+ * Tools: docker_container_logs, docker_worker_logs, docker_container_list
+ * Config: .dockerlogs.yml
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { containerLogsTool, workerLogsTool, listContainersTool } from "./tools/logs";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool(containerLogsTool);
+  pi.registerTool(workerLogsTool);
+  pi.registerTool(listContainersTool);
+}

package/src/tools/logs.ts

@@ -0,0 +1,237 @@
+import { Type } from "typebox";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../config";
+import { dockerLogs, listContainers, resolveWorkerContainer, grepLogs, truncateOutput } from "../helpers";
+
+// ─── Container Logs ────────────────────────────────────────────────────────────
+
+export const containerLogsTool = {
+  name: "docker_container_logs" as const,
+  label: "Get Docker Container Logs",
+  description:
+    "Fetch logs from a Docker container by name using `docker logs`. Supports tail, since, and text search filtering. Works with any container on the Docker host.",
+  parameters: Type.Object({
+    container: Type.String({
+      description: "Docker container name (e.g. 'ai-factory-worker-1', 'ai-factory-orchestrator')",
+    }),
+    tail: Type.Optional(Type.Number({ description: "Number of lines to tail (default: 200)" })),
+    since: Type.Optional(Type.String({ description: "Only logs since (e.g. '10m', '1h', ISO timestamp)" })),
+    search: Type.Optional(Type.String({ description: "Filter lines containing this text (case-insensitive)" })),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const config = loadConfig(ctx.cwd);
+    const tail = params.tail || config.tail;
+
+    const result = await dockerLogs(params.container, tail, params.since);
+
+    if (!result.ok) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: [
+              `❌ Failed to get logs for "${params.container}":`,
+              `   ${result.error}`,
+              "",
+              `Check: Is Docker running? Is the container name correct?`,
+              `Try: docker_container_list() to see running containers.`,
+            ].join("\n"),
+          },
+        ],
+        isError: true,
+        details: { container: params.container },
+      };
+    }
+
+    let text = result.text!;
+    let grepInfo = "";
+
+    if (params.search) {
+      text = grepLogs(text, params.search);
+      grepInfo = ` (filtered by "${params.search}")`;
+    }
+
+    const lines = text.split("\n").filter(Boolean);
+    if (lines.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `📋 No log entries found for "${params.container}"${grepInfo}.`,
+          },
+        ],
+        details: { container: params.container, count: 0 },
+      };
+    }
+
+    const output = truncateOutput(text, tail);
+    let header = `📋 ${params.container} — ${lines.length} lines${grepInfo}`;
+    if (output.truncated) {
+      header += ` (showing truncated view, total: ${output.totalLines} lines)`;
+    }
+
+    return {
+      content: [{ type: "text", text: `${header}\n\n${output.text}` }],
+      details: {
+        container: params.container,
+        count: lines.length,
+        totalLines: output.totalLines,
+        truncated: output.truncated,
+      },
+    };
+  },
+};
+
+// ─── Worker Logs ───────────────────────────────────────────────────────────────
+
+export const workerLogsTool = {
+  name: "docker_worker_logs" as const,
+  label: "Get Worker Container Logs",
+  description:
+    "Fetch logs from a wrok.in factory worker container. Resolves worker numbers (1-4) to container names automatically.",
+  parameters: Type.Object({
+    worker: Type.String({
+      description: 'Worker identifier: "1" through "4", "worker-2", or full container name',
+    }),
+    tail: Type.Optional(Type.Number({ description: "Number of lines to tail (default: 200)" })),
+    since: Type.Optional(Type.String({ description: "Only logs since (e.g. '10m', '1h')" })),
+    search: Type.Optional(Type.String({ description: "Filter lines containing this text" })),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const config = loadConfig(ctx.cwd);
+    const container = resolveWorkerContainer(params.worker);
+
+    if (!container) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `❌ Could not resolve worker "${params.worker}" to a container name.\n   Try: "1", "worker-2", or "ai-factory-worker-3".`,
+          },
+        ],
+        isError: true,
+        details: { worker: params.worker },
+      };
+    }
+
+    const tail = params.tail || config.tail;
+    const result = await dockerLogs(container, tail, params.since);
+
+    if (!result.ok) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: [
+              `❌ Failed to get logs for worker "${params.worker}" (container: ${container}):`,
+              `   ${result.error}`,
+            ].join("\n"),
+          },
+        ],
+        isError: true,
+        details: { worker: params.worker, container },
+      };
+    }
+
+    let text = result.text!;
+    let grepInfo = "";
+
+    if (params.search) {
+      text = grepLogs(text, params.search);
+      grepInfo = ` (filtered by "${params.search}")`;
+    }
+
+    const lines = text.split("\n").filter(Boolean);
+    if (lines.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `📋 No log entries for worker ${params.worker}${grepInfo}.`,
+          },
+        ],
+        details: { worker: params.worker, container, count: 0 },
+      };
+    }
+
+    const output = truncateOutput(text, tail);
+    let header = `📋 Worker ${params.worker} (${container}) — ${lines.length} lines${grepInfo}`;
+    if (output.truncated) {
+      header += ` (showing truncated view, total: ${output.totalLines} lines)`;
+    }
+
+    return {
+      content: [{ type: "text", text: `${header}\n\n${output.text}` }],
+      details: {
+        worker: params.worker,
+        container,
+        count: lines.length,
+        totalLines: output.totalLines,
+        truncated: output.truncated,
+      },
+    };
+  },
+};
+
+// ─── List Containers ───────────────────────────────────────────────────────────
+
+export const listContainersTool = {
+  name: "docker_container_list" as const,
+  label: "List Factory Containers",
+  description:
+    "List running Docker containers related to the AI factory. Shows container names so you know what to pass to docker_container_logs().",
+  parameters: Type.Object({}),
+  async execute(_id: string, _params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const result = await listContainers();
+
+    if (!result.ok) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `❌ Failed to list containers: ${result.error}`,
+          },
+        ],
+        isError: true,
+        details: {},
+      };
+    }
+
+    const containers = result.containers!;
+
+    if (containers.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: "No factory containers running. Is the factory started? (`docker compose up -d` in the wrok.in directory)",
+          },
+        ],
+        details: { count: 0 },
+      };
+    }
+
+    const lines = [`🐳 Running Factory Containers (${containers.length})`, ""];
+    for (const c of containers) {
+      const type = c.includes("worker")
+        ? "🔵 Worker"
+        : c.includes("orchestrator")
+          ? "🟡 Orchestrator"
+          : c.includes("gitea")
+            ? "📦 Gitea"
+            : c.includes("postgres")
+              ? "🗄️  Postgres"
+              : c.includes("loki")
+                ? "📊 Loki"
+                : c.includes("grafana")
+                  ? "📈 Grafana"
+                  : "⚪ Other";
+      lines.push(`   ${type}  ${c}`);
+    }
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: { containers, count: containers.length },
+    };
+  },
+};

package/src/types.ts

@@ -0,0 +1,12 @@
+/**
+ * pi-docker-logs — Types
+ */
+
+export interface DockerLogsConfig {
+  /** Default number of lines to tail */
+  tail: number;
+}
+
+export const DEFAULT_CONFIG: DockerLogsConfig = {
+  tail: 200,
+};