glink-engine 0.3.0__tar.gz

glink_engine-0.3.0/.gitignore

@@ -0,0 +1,12 @@
+pycache/
+*.pyc
+__pycache__/
+.ruff_cache/
+.mypy_cache/
+*.bak
+*.bak2
+*.fresh
+*.log
+forge-audit-*.md
+forge-arbitration.md
+checkpoints/

glink_engine-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gary Lin
+
+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.

glink_engine-0.3.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: glink-engine
+Version: 0.3.0
+Summary: Multi-Agent Workflow Orchestration Engine. One Bus. Zero Friction.
+Author: Gary Lin
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,automation,orchestration,pipeline,workflow
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Glink
+
+> **Multi-Agent Workflow Orchestration. One Bus. Zero Friction.**
+
+Glink is a lightweight orchestration engine that turns your AI agents into a **collaborative assembly line**. Define a workflow in YAML, and Glink routes each step to the right agent — passing context, handling failures, and logging every heartbeat onto a shared event bus.
+
+No database. No message queue. No external dependencies.
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                     Glink Daemon                          │
+│                                                           │
+│  ┌─────────────────────────────────────────────────────┐  │
+│  │                    Main Bus                          │  │
+│  │              Append-only JSONL Timeline              │  │
+│  └──────┬──────────┬──────────┬──────────┬─────────────┘  │
+│         │          │          │          │                │
+│    ┌────▼───┐ ┌───▼────┐ ┌───▼────┐ ┌──▼──────┐         │
+│    │Agent-1 │ │Agent-2 │ │Agent-3 │ │...      │         │
+│    │:8420   │ │:8431   │ │:8432   │ │         │         │
+│    └────────┘ └────────┘ └────────┘ └─────────┘         │
+│         │          │          │          │                │
+│         └──────────┴──────────┴──────────┘                │
+│                    Your AI Fleet                          │
+└──────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Quick Start
+
+```bash
+# Define your agents in main.py or daemon/core.py
+# Default port mapping (customize freely):
+#   agent-1 :8420 (generalist)
+#   agent-2 :8431 (backend)
+#   agent-3 :8432 (frontend/UI)
+#   agent-4 :8434 (data)
+#   agent-5 :8435 (testing)
+
+# Run a workflow (auto-resumes from last checkpoint)
+python3 glink-daemon.py my-workflow
+
+# Force restart from step 1
+python3 glink-daemon.py my-workflow --force
+
+# Jump to a specific step
+python3 glink-daemon.py my-workflow --step 4
+
+# Serve-only mode (API daemon without running workflow)
+python3 glink-daemon.py --serve
+
+# Open dashboard
+open http://127.0.0.1:8426/commander.html
+```
+
+---
+
+## Features
+
+| Feature | Description |
+|:--------|:------------|
+| **YAML Workflows** | Define steps, agents, dependencies, and fallbacks in one file |
+| **Main Bus** | JSONL blackboard — append-only, agent-agnostic, replayable |
+| **Smart Routing** | Primary agent down? Auto-fallback to the next in line |
+| **Checkpoint Resume** | Crash mid-workflow? Restart picks up where it left off |
+| **Dependency Graph** | Steps can `depends_on` each other; Glink handles ordering |
+| **Retry Loop** | Auto-retry failed steps (configurable, default 2×) |
+| **HTTP API + SSE** | Live status, agent health, and event stream on `:8426` |
+| **Self-Healing** | Daemon auto-restarts on crash, PID-based watchdog |
+| **Webhook Alerts** | Push notifications to any HTTP endpoint |
+| **Zero External Deps** | Pure Python 3.10+, standard library. No pip install. |
+
+---
+
+## Define a Workflow
+
+```yaml
+name: my-pipeline
+version: 1.0.0
+description: "A simple 3-step demo"
+
+global_context: |
+  You are part of a multi-agent orchestration pipeline.
+  Build upon the output of previous steps.
+
+steps:
+  - id: step-1
+    executor: agent-1
+    title: "Generate content"
+    output_file: projects/demo/step1.txt
+    task: |
+      Create a summary of what makes a good multi-agent workflow.
+
+  - id: step-2
+    executor: agent-2
+    title: "Enhance"
+    input_file: projects/demo/step1.txt
+    output_file: projects/demo/step2.md
+    task: |
+      Read and enhance the step-1 output. Add code examples.
+
+  - id: step-3
+    executor: agent-3
+    title: "Verify"
+    input_file: projects/demo/step2.md
+    output_file: projects/demo/VERIFIED.md
+    task: |
+      Verify the enhanced document is complete.
+      Append a verification seal if all checks pass.
+```
+
+---
+
+## API Reference
+
+All endpoints served on the configured port (`:8426` by default).
+
+| Method | Endpoint | Description |
+|:-------|:---------|:------------|
+| `GET` | `/health` | Liveness check |
+| `GET` | `/status` | Full project status + step-by-step progress |
+| `GET` | `/status/agents` | Which agents are online |
+| `GET` | `/status/events?n=20` | Last N bus events |
+| `GET` | `/intel/step` | Detailed intelligence per step stage |
+| `GET` | `/intel/agents` | Agent-specific metrics |
+| `GET` | `/intel/timeline` | Step timeline visualization data |
+| `GET` | `/events/stream` | SSE real-time event stream |
+| `POST` | `/restart` | Resume from last checkpoint |
+| `POST` | `/restart?force` | Force restart from step 1 |
+| `POST` | `/restart?step=N` | Jump to specific step |
+
+---
+
+## Configuration
+
+See `glink-config.yaml`:
+
+```yaml
+project:
+  default: hello-world
+
+scheduling:
+  max_retries: 2
+  poll_interval: 3
+  poll_max_wait: 180
+  max_concurrent_steps: 1
+
+reporting:
+  channels:
+    - type: console
+      label: "Glink"
+    # - type: webhook
+    #   url: "https://hooks.example.com/..."
+    #   label: "Slack"
+
+server:
+  host: "127.0.0.1"
+  port: 8426
+
+security:
+  startup_timeout: 10
+```
+
+Environment variables:
+- `GLINK_DEFAULT_PROJECT` — override default project name
+- `GLINK_PORT` — override API server port
+- `GLINK_REPORTER` — set to `webhook`, `console`, or `silent`
+- `GLINK_ALERT_WEBHOOK` — webhook URL for alerts
+
+---
+
+## Real-World Usage
+
+Glink was used to orchestrate a **10-step game development pipeline** across 5 agents:
+
+- Step 1-4: 3D scene, physics, textures, UI
+- Step 5-6: Game systems (save/load, scoring)
+- Step 7-8: Quality verification
+- Result: Single playable HTML file, 97 KB / 2,751 lines
+
+All built by agent collaboration — zero lines of human-written code.
+
+---
+
+## Project Structure
+
+```
+glink/
+├── glink-daemon.py         # CLI entry point
+├── glink-config.yaml        # Configuration
+├── daemon/
+│   ├── core.py              # Workflow orchestration engine
+│   ├── api.py               # HTTP API server (17 endpoints)
+│   ├── checks.py            # PID management & auto-recovery
+│   ├── config.py            # Config loader
+│   └── log.py               # Reporter initialization
+├── bus/
+│   ├── main_bus.py          # JSONL event bus
+│   └── agent_client.py      # Agent HTTP client
+├── reporter/
+│   └── reporter.py          # Notification session (webhook/console)
+├── dashboard/
+│   ├── commander.html       # C2 dashboard (realtime)
+│   └── index.html           # Legacy dashboard
+├── workflows/               # Your YAML workflow definitions
+└── projects/                # Step outputs by project
+```
+
+---
+
+## License
+
+MIT — free for any use, open or commercial.

glink_engine-0.3.0/README.md

@@ -0,0 +1,218 @@
+# Glink
+
+> **Multi-Agent Workflow Orchestration. One Bus. Zero Friction.**
+
+Glink is a lightweight orchestration engine that turns your AI agents into a **collaborative assembly line**. Define a workflow in YAML, and Glink routes each step to the right agent — passing context, handling failures, and logging every heartbeat onto a shared event bus.
+
+No database. No message queue. No external dependencies.
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                     Glink Daemon                          │
+│                                                           │
+│  ┌─────────────────────────────────────────────────────┐  │
+│  │                    Main Bus                          │  │
+│  │              Append-only JSONL Timeline              │  │
+│  └──────┬──────────┬──────────┬──────────┬─────────────┘  │
+│         │          │          │          │                │
+│    ┌────▼───┐ ┌───▼────┐ ┌───▼────┐ ┌──▼──────┐         │
+│    │Agent-1 │ │Agent-2 │ │Agent-3 │ │...      │         │
+│    │:8420   │ │:8431   │ │:8432   │ │         │         │
+│    └────────┘ └────────┘ └────────┘ └─────────┘         │
+│         │          │          │          │                │
+│         └──────────┴──────────┴──────────┘                │
+│                    Your AI Fleet                          │
+└──────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Quick Start
+
+```bash
+# Define your agents in main.py or daemon/core.py
+# Default port mapping (customize freely):
+#   agent-1 :8420 (generalist)
+#   agent-2 :8431 (backend)
+#   agent-3 :8432 (frontend/UI)
+#   agent-4 :8434 (data)
+#   agent-5 :8435 (testing)
+
+# Run a workflow (auto-resumes from last checkpoint)
+python3 glink-daemon.py my-workflow
+
+# Force restart from step 1
+python3 glink-daemon.py my-workflow --force
+
+# Jump to a specific step
+python3 glink-daemon.py my-workflow --step 4
+
+# Serve-only mode (API daemon without running workflow)
+python3 glink-daemon.py --serve
+
+# Open dashboard
+open http://127.0.0.1:8426/commander.html
+```
+
+---
+
+## Features
+
+| Feature | Description |
+|:--------|:------------|
+| **YAML Workflows** | Define steps, agents, dependencies, and fallbacks in one file |
+| **Main Bus** | JSONL blackboard — append-only, agent-agnostic, replayable |
+| **Smart Routing** | Primary agent down? Auto-fallback to the next in line |
+| **Checkpoint Resume** | Crash mid-workflow? Restart picks up where it left off |
+| **Dependency Graph** | Steps can `depends_on` each other; Glink handles ordering |
+| **Retry Loop** | Auto-retry failed steps (configurable, default 2×) |
+| **HTTP API + SSE** | Live status, agent health, and event stream on `:8426` |
+| **Self-Healing** | Daemon auto-restarts on crash, PID-based watchdog |
+| **Webhook Alerts** | Push notifications to any HTTP endpoint |
+| **Zero External Deps** | Pure Python 3.10+, standard library. No pip install. |
+
+---
+
+## Define a Workflow
+
+```yaml
+name: my-pipeline
+version: 1.0.0
+description: "A simple 3-step demo"
+
+global_context: |
+  You are part of a multi-agent orchestration pipeline.
+  Build upon the output of previous steps.
+
+steps:
+  - id: step-1
+    executor: agent-1
+    title: "Generate content"
+    output_file: projects/demo/step1.txt
+    task: |
+      Create a summary of what makes a good multi-agent workflow.
+
+  - id: step-2
+    executor: agent-2
+    title: "Enhance"
+    input_file: projects/demo/step1.txt
+    output_file: projects/demo/step2.md
+    task: |
+      Read and enhance the step-1 output. Add code examples.
+
+  - id: step-3
+    executor: agent-3
+    title: "Verify"
+    input_file: projects/demo/step2.md
+    output_file: projects/demo/VERIFIED.md
+    task: |
+      Verify the enhanced document is complete.
+      Append a verification seal if all checks pass.
+```
+
+---
+
+## API Reference
+
+All endpoints served on the configured port (`:8426` by default).
+
+| Method | Endpoint | Description |
+|:-------|:---------|:------------|
+| `GET` | `/health` | Liveness check |
+| `GET` | `/status` | Full project status + step-by-step progress |
+| `GET` | `/status/agents` | Which agents are online |
+| `GET` | `/status/events?n=20` | Last N bus events |
+| `GET` | `/intel/step` | Detailed intelligence per step stage |
+| `GET` | `/intel/agents` | Agent-specific metrics |
+| `GET` | `/intel/timeline` | Step timeline visualization data |
+| `GET` | `/events/stream` | SSE real-time event stream |
+| `POST` | `/restart` | Resume from last checkpoint |
+| `POST` | `/restart?force` | Force restart from step 1 |
+| `POST` | `/restart?step=N` | Jump to specific step |
+
+---
+
+## Configuration
+
+See `glink-config.yaml`:
+
+```yaml
+project:
+  default: hello-world
+
+scheduling:
+  max_retries: 2
+  poll_interval: 3
+  poll_max_wait: 180
+  max_concurrent_steps: 1
+
+reporting:
+  channels:
+    - type: console
+      label: "Glink"
+    # - type: webhook
+    #   url: "https://hooks.example.com/..."
+    #   label: "Slack"
+
+server:
+  host: "127.0.0.1"
+  port: 8426
+
+security:
+  startup_timeout: 10
+```
+
+Environment variables:
+- `GLINK_DEFAULT_PROJECT` — override default project name
+- `GLINK_PORT` — override API server port
+- `GLINK_REPORTER` — set to `webhook`, `console`, or `silent`
+- `GLINK_ALERT_WEBHOOK` — webhook URL for alerts
+
+---
+
+## Real-World Usage
+
+Glink was used to orchestrate a **10-step game development pipeline** across 5 agents:
+
+- Step 1-4: 3D scene, physics, textures, UI
+- Step 5-6: Game systems (save/load, scoring)
+- Step 7-8: Quality verification
+- Result: Single playable HTML file, 97 KB / 2,751 lines
+
+All built by agent collaboration — zero lines of human-written code.
+
+---
+
+## Project Structure
+
+```
+glink/
+├── glink-daemon.py         # CLI entry point
+├── glink-config.yaml        # Configuration
+├── daemon/
+│   ├── core.py              # Workflow orchestration engine
+│   ├── api.py               # HTTP API server (17 endpoints)
+│   ├── checks.py            # PID management & auto-recovery
+│   ├── config.py            # Config loader
+│   └── log.py               # Reporter initialization
+├── bus/
+│   ├── main_bus.py          # JSONL event bus
+│   └── agent_client.py      # Agent HTTP client
+├── reporter/
+│   └── reporter.py          # Notification session (webhook/console)
+├── dashboard/
+│   ├── commander.html       # C2 dashboard (realtime)
+│   └── index.html           # Legacy dashboard
+├── workflows/               # Your YAML workflow definitions
+└── projects/                # Step outputs by project
+```
+
+---
+
+## License
+
+MIT — free for any use, open or commercial.

glink_engine-0.3.0/bus/__init__.py

@@ -0,0 +1,12 @@
+# SPDX-License-Identifier: MIT
+"""Glink Bus 包 — 共享工具与总线模块"""
+
+import re
+
+# ── 项目名白名单：仅允许字母、数字、下划线、连字符（防 path traversal）──
+_PROJECT_NAME_RE = re.compile(r"[^\w\-]")
+
+
+def sanitize_project_name(project_name: str) -> str:
+    """过滤项目名，防止 path traversal（仅保留 [\\w\\-]）"""
+    return _PROJECT_NAME_RE.sub("", project_name or "")

glink_engine-0.3.0/bus/agent_client.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""
+agent_client — Glink 共享的 Agent 通讯与工作流加载模块
+
+由 glink.py（一次性调度引擎）和 glink-daemon.py（带断点续跑的守护进程）共享。
+
+导出：
+- AGENT_PORTS:  Agent 名称 → HTTP 端口的统一映射
+- call_agent(): HTTP 调用 Agent 的 /ask 接口
+- load_workflow(): 从 workflows/ 或 bus/projects/ 加载 yaml 工作流
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+from typing import Any
+
+import yaml
+
+# ── Agent 端口映射（唯一真源）────────────────────────────
+# 同一端口可有多个别名（如 标准版/扎古、代码臂/Forge/forge）
+AGENT_PORTS: dict[str, int] = {
+    "标准版": 8420,
+    "扎古": 8420,
+    "重锤": 8431,
+    "绘墨": 8432,
+    "大黄蜂": 8434,
+    "Laser": 8435,
+    "代码臂": 8436,
+    "Forge": 8436,
+    "forge": 8436,
+}
+
+DEFAULT_AGENT_PORT = 8420
+DEFAULT_TIMEOUT = 600
+
+# ── 项目名白名单（防 path traversal，从 bus/__init__.py 导入）──
+from . import sanitize_project_name
+
+_sanitize_project_name = sanitize_project_name  # 兼容别名
+
+
+# ── HTTP 调用 Agent ─────────────────────────────────────
+def call_agent(
+    agent: str,
+    task: str,
+    port: int | None = None,
+    timeout: int = DEFAULT_TIMEOUT,
+    parse_reply: bool = True,
+) -> dict[str, Any]:
+    """HTTP 调用 agent 的 /ask 接口。
+
+    Args:
+        agent:        Agent 名称（如 "重锤"、"Forge"）
+        task:         发送给 Agent 的任务描述
+        port:         显式端口；不传则查 AGENT_PORTS
+        timeout:      请求超时秒数
+        parse_reply:  True=尝试解析 JSON 取 reply 字段；False=直接返回原始响应
+
+    Returns:
+        {"status": "ok",     "output": "<reply 或原始响应前500字>"}
+        {"status": "failed", "error":  "<错误描述>"}
+    """
+    if port is None:
+        port = AGENT_PORTS.get(agent, DEFAULT_AGENT_PORT)
+
+    url = f"http://127.0.0.1:{port}/ask"
+    payload = json.dumps({"message": task, "session": True}).encode()
+    req = urllib.request.Request(url, data=payload, headers={"Content-Type": "application/json"})
+
+    max_response_size = 1 * 1024 * 1024  # 1 MB
+    chunk_size = 64 * 1024  # 64 KB
+
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            chunks = []
+            total = 0
+            while True:
+                chunk = resp.read(chunk_size)
+                if not chunk:
+                    break
+                total += len(chunk)
+                if total > max_response_size:
+                    max_read = max_response_size - (total - len(chunk))
+                    if max_read > 0:
+                        chunks.append(chunk[:max_read])
+                    while resp.read(chunk_size):
+                        pass
+                    body = b"".join(chunks).decode()
+                    body = body[:max_response_size] + "\n\n[TRUNCATED: Response exceeded 1MB limit]"
+                    break
+                chunks.append(chunk)
+            else:
+                body = b"".join(chunks).decode()
+
+            if parse_reply:
+                try:
+                    output = json.loads(body).get("reply", body[:500])
+                except json.JSONDecodeError:
+                    output = body[:500]
+            else:
+                output = body[:500]
+            return {"status": "ok", "output": output}
+    except urllib.error.HTTPError as e:
+        body = e.read().decode()[:200]
+        return {"status": "failed", "error": f"HTTP {e.code}: {body}"}
+    except Exception as e:
+        return {"status": "failed", "error": str(e)}
+
+
+# ── 工作流加载 ───────────────────────────────────────────
+def load_workflow(project_name: str, base_dir: str | None = None) -> dict[str, Any]:
+    """加载工作流 YAML，先查 workflows/，再查 bus/projects/。
+
+    Args:
+        project_name: 项目名（会被白名单过滤）
+        base_dir:     Glink 根目录；不传则用本文件所在目录的父级
+
+    Returns:
+        解析后的工作流字典
+
+    Raises:
+        SystemExit(1): 找不到工作流文件
+    """
+    if base_dir is None:
+        # 本文件位于 <glink>/bus/agent_client.py，父级 = glink 根
+        base_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+    workflows_dir = os.path.join(base_dir, "workflows")
+    bus_projects_dir = os.path.join(base_dir, "bus", "projects")
+
+    safe_name = _sanitize_project_name(project_name)
+    candidates = [
+        os.path.join(workflows_dir, f"{safe_name}.yaml"),
+        os.path.join(bus_projects_dir, f"{safe_name}.yaml"),
+    ]
+
+    for path in candidates:
+        if os.path.exists(path):
+            with open(path, encoding="utf-8") as f:
+                return yaml.safe_load(f)
+
+    print(f"❌ 找不到工作流: {safe_name}", file=sys.stderr)
+    sys.exit(1)