@fickydev/pigent 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -34,6 +34,11 @@
 - Added short `pigent` command shim for `status`, `logs`, `start`, `stop`, `restart`, `update`, and `setup`.
 - Simplified published CLI flow so `bunx @fickydev/pigent` runs setup and starts Pigent without install/start/typecheck prompts.
 - Added automatic database migrations at daemon startup.
+- Added `HeartbeatRepository` for creating, updating, and querying heartbeat runs.
+- Added `AgentRegistry` to centralize loaded agent/profile lookup and agent DB sync.
+- Added safe Pi runner failure replies with internal error persistence.
+- Added per-session locking to serialize Pi runs for the same agent/channel/chat/thread.
+- Added Telegram chat instructions to Pi prompt composition.
 - Kept daemon process alive after startup so CLI runs do not exit after `pigent ready`.
 
 ### Changed

package/TODO.md

@@ -66,12 +66,12 @@
 - [x] Define `messages` table
 - [x] Define `heartbeats` table
 - [x] Define `runtime_kv` table for offsets and daemon state
-- [ ] Implement repositories
+- [x] Implement repositories
   - [x] `AgentRepository`
   - [x] `SessionRepository`
   - [x] `MessageRepository`
   - [x] `TelegramRepository`
-  - [ ] `HeartbeatRepository`
+  - [x] `HeartbeatRepository`
 
 ## Channel Layer
 
@@ -106,18 +106,18 @@
 
 ## Agent Runtime
 
-- [ ] Implement `AgentRegistry`
+- [x] Implement `AgentRegistry`
 - [x] Implement `AgentDaemon`
 - [x] Implement `AgentRunner`
 - [ ] Implement `PiSessionFactory`
 - [x] Implement `PiAgentRunner`
 - [x] Create/get session by `agentId + channel + chatId + threadId`
-- [ ] Compose prompt with chat instructions
+- [x] Compose prompt with chat instructions
 - [x] Compose basic channel/chat/user prompt for Pi runner
 - [x] Persist inbound message before Pi run
 - [x] Persist outbound response after Pi run
-- [ ] Handle Pi errors and send safe error reply
-- [ ] Add per-session lock to prevent concurrent Pi runs
+- [x] Handle Pi errors and send safe error reply
+- [x] Add per-session lock to prevent concurrent Pi runs
 
 ## Pi Integration
 
@@ -136,7 +136,7 @@
 - [ ] Add per-agent heartbeat lock
 - [ ] Add heartbeat prompt composition
 - [ ] Add `NOOP` handling
-- [ ] Persist heartbeat start/result/failure
+- [x] Persist heartbeat start/result/failure
 - [ ] Add notification cooldown
 - [ ] Add max heartbeat messages per hour
 - [ ] Send heartbeat output to configured channel only when useful
@@ -156,7 +156,7 @@
 ## Commands UX
 
 - [x] `/agents` list agents available in chat
-- [ ] `/agent <id> <message>` route message
+- [x] `/agent <id> <message>` route message
 - [ ] `/default-agent <id>` set chat default
 - [ ] `/instructions <text>` set chat instructions
 - [ ] `/sessions` list active sessions for chat

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fickydev/pigent",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "private": false,
   "type": "module",
   "description": "Autonomous multi-agent daemon using Pi as core execution engine.",

package/src/agents/AgentRegistry.ts

@@ -0,0 +1,45 @@
+import type { LoadedAgentConfig, LoadedConfig, ProfileConfig } from "../config/schemas";
+import type { Repositories } from "../db/repositories";
+
+export class AgentRegistry {
+  private readonly agentsById: Map<string, LoadedAgentConfig>;
+  private readonly profilesById: Map<string, ProfileConfig>;
+
+  constructor(
+    private readonly config: LoadedConfig,
+    private readonly repositories: Repositories,
+  ) {
+    this.agentsById = new Map(config.agents.map((agent) => [agent.id, agent]));
+    this.profilesById = new Map(config.profiles.map((profile) => [profile.id, profile]));
+  }
+
+  async syncConfiguredAgents(): Promise<void> {
+    for (const agent of this.listAgents()) {
+      await this.repositories.agents.upsertLoadedAgent(agent);
+    }
+  }
+
+  listAgents(): LoadedAgentConfig[] {
+    return [...this.agentsById.values()];
+  }
+
+  listProfiles(): ProfileConfig[] {
+    return [...this.profilesById.values()];
+  }
+
+  getAgent(id: string): LoadedAgentConfig | null {
+    return this.agentsById.get(id) ?? null;
+  }
+
+  getProfile(id: string): ProfileConfig | null {
+    return this.profilesById.get(id) ?? null;
+  }
+
+  hasAgent(id: string): boolean {
+    return this.agentsById.has(id);
+  }
+
+  defaultAgentId(): string | null {
+    return this.listAgents()[0]?.id ?? null;
+  }
+}

package/src/agents/AgentRunner.ts

@@ -1,8 +1,8 @@
 import type { InboundMessage } from "../channels/types";
-import type { LoadedAgentConfig, LoadedConfig, ProfileConfig } from "../config/schemas";
 import type { Repositories } from "../db/repositories";
 import { logger } from "../logging/logger";
 import { PiAgentRunner } from "../pi/PiAgentRunner";
+import type { AgentRegistry } from "./AgentRegistry";
 
 export type AgentRunInput = {
   agentId: string;
@@ -10,15 +10,29 @@ export type AgentRunInput = {
   message: InboundMessage;
 };
 
+type AgentRunResponse = {
+  text: string;
+  error?: string;
+};
+
+function sessionLockKey(input: AgentRunInput): string {
+  return [input.agentId, input.message.channel, input.message.chatId, input.message.threadId ?? ""].join(":");
+}
+
 export class AgentRunner {
   private readonly piRunner = new PiAgentRunner();
+  private readonly sessionLocks = new Map<string, Promise<void>>();
 
   constructor(
-    private readonly config: LoadedConfig,
+    private readonly registry: AgentRegistry,
     private readonly repositories: Repositories,
   ) {}
 
   async run(input: AgentRunInput): Promise<string> {
+    return this.withSessionLock(input, () => this.runUnlocked(input));
+  }
+
+  private async runUnlocked(input: AgentRunInput): Promise<string> {
     const session = await this.repositories.sessions.getOrCreate({
       agentId: input.agentId,
       channel: input.message.channel,
@@ -38,7 +52,20 @@ export class AgentRunner {
       rawJson: input.message.raw,
     });
 
-    const response = await this.createResponse(input);
+    const chatInstructions = await this.chatInstructions(input);
+    const response = await this.createResponse(input, chatInstructions);
+
+    if (response.error) {
+      await this.repositories.messages.create({
+        agentId: input.agentId,
+        sessionId: session.id,
+        channel: input.message.channel,
+        direction: "internal",
+        chatId: input.message.chatId,
+        threadId: input.message.threadId,
+        content: response.error,
+      });
+    }
 
     await this.repositories.messages.create({
       agentId: input.agentId,
@@ -47,41 +74,65 @@ export class AgentRunner {
       direction: "outbound",
       chatId: input.message.chatId,
       threadId: input.message.threadId,
-      content: response,
+      content: response.text,
     });
 
-    return response;
+    return response.text;
   }
 
-  private async createResponse(input: AgentRunInput): Promise<string> {
+  private async withSessionLock<T>(input: AgentRunInput, task: () => Promise<T>): Promise<T> {
+    const key = sessionLockKey(input);
+    const previous = this.sessionLocks.get(key) ?? Promise.resolve();
+    const run = previous.catch(() => undefined).then(task);
+    const tail = run.then(
+      () => undefined,
+      () => undefined,
+    );
+
+    this.sessionLocks.set(key, tail);
+
+    try {
+      return await run;
+    } finally {
+      if (this.sessionLocks.get(key) === tail) {
+        this.sessionLocks.delete(key);
+      }
+    }
+  }
+
+  private async createResponse(input: AgentRunInput, chatInstructions: string): Promise<AgentRunResponse> {
     if (process.env.PIGENT_FAKE_AGENT === "1") {
-      return this.fakeResponse(input.agentId, input.text);
+      return { text: this.fakeResponse(input.agentId, input.text) };
     }
 
-    const agent = this.findAgent(input.agentId);
-    if (!agent) return `Unknown agent: ${input.agentId}`;
+    const agent = this.registry.getAgent(input.agentId);
+    if (!agent) return { text: `Unknown agent: ${input.agentId}` };
 
     try {
-      return await this.piRunner.run({
+      const text = await this.piRunner.run({
         agent,
-        profile: this.findProfile(agent.profile),
-        prompt: this.composePrompt(input),
+        profile: this.registry.getProfile(agent.profile),
+        prompt: this.composePrompt(input, chatInstructions),
       });
+
+      return { text };
     } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+
       logger.error("pi runner failed", {
         agentId: input.agentId,
-        error: error instanceof Error ? error.message : String(error),
+        error: errorMessage,
       });
 
       if (process.env.PIGENT_FALLBACK_FAKE_AGENT === "1") {
-        return this.fakeResponse(input.agentId, input.text);
+        return { text: this.fakeResponse(input.agentId, input.text), error: errorMessage };
       }
 
-      return "Agent execution failed. Check daemon logs.";
+      return { text: "Agent failed to respond. Please try again later.", error: errorMessage };
     }
   }
 
-  private composePrompt(input: AgentRunInput): string {
+  private composePrompt(input: AgentRunInput, chatInstructions: string): string {
     return [
       `[Channel]\n${input.message.channel}`,
       `[Chat]\n${input.message.chatId}`,
@@ -89,24 +140,24 @@ export class AgentRunner {
       input.message.senderName || input.message.senderId
         ? `[User]\n${input.message.senderName ?? input.message.senderId}`
         : null,
+      chatInstructions ? `[Chat Instructions]\n${chatInstructions}` : null,
       `[Message]\n${input.text}`,
     ]
       .filter(Boolean)
       .join("\n\n");
   }
 
-  private fakeResponse(agentId: string, text: string): string {
-    const agent = this.findAgent(agentId);
-    const name = agent?.name ?? agentId;
+  private async chatInstructions(input: AgentRunInput): Promise<string> {
+    if (input.message.channel !== "telegram") return "";
 
-    return `[${name}] fake runner received: ${text || "(empty message)"}`;
+    const chat = await this.repositories.telegram.findChat(input.message.chatId);
+    return chat?.instructions.trim() ?? "";
   }
 
-  private findAgent(agentId: string): LoadedAgentConfig | null {
-    return this.config.agents.find((candidate) => candidate.id === agentId) ?? null;
-  }
+  private fakeResponse(agentId: string, text: string): string {
+    const agent = this.registry.getAgent(agentId);
+    const name = agent?.name ?? agentId;
 
-  private findProfile(profileId: string): ProfileConfig | null {
-    return this.config.profiles.find((candidate) => candidate.id === profileId) ?? null;
+    return `[${name}] fake runner received: ${text || "(empty message)"}`;
   }
 }

package/src/agents/BotCommandHandler.ts

@@ -1,6 +1,6 @@
 import type { InboundMessage } from "../channels/types";
-import type { LoadedConfig } from "../config/schemas";
 import type { Repositories } from "../db/repositories";
+import type { AgentRegistry } from "./AgentRegistry";
 
 export type BotCommandResult =
   | {
@@ -13,7 +13,7 @@ export type BotCommandResult =
 
 export class BotCommandHandler {
   constructor(
-    private readonly config: LoadedConfig,
+    private readonly registry: AgentRegistry,
     private readonly repositories: Repositories,
   ) {}
 
@@ -48,7 +48,7 @@ export class BotCommandHandler {
       return "No agents configured for this chat.";
     }
 
-    const allAgentIds = this.config.agents.map((agent) => agent.id);
+    const allAgentIds = this.registry.listAgents().map((agent) => agent.id);
     const allowedAgentIds = [];
 
     for (const agentId of allAgentIds) {

package/src/agents/MessageRouter.ts

@@ -1,5 +1,6 @@
 import type { InboundMessage } from "../channels/types";
 import type { Repositories } from "../db/repositories";
+import type { AgentRegistry } from "./AgentRegistry";
 
 export type RouteResult =
   | {
@@ -14,7 +15,10 @@ export type RouteResult =
     };
 
 export class MessageRouter {
-  constructor(private readonly repositories: Repositories) {}
+  constructor(
+    private readonly repositories: Repositories,
+    private readonly registry: AgentRegistry,
+  ) {}
 
   async route(message: InboundMessage): Promise<RouteResult> {
     if (message.channel !== "telegram") {
@@ -54,8 +58,7 @@ export class MessageRouter {
       };
     }
 
-    const agent = await this.repositories.agents.findById(agentId);
-    if (!agent) {
+    if (!this.registry.hasAgent(agentId)) {
       return {
         ok: false,
         reason: "unknown_agent",

package/src/cli/run.ts

@@ -63,12 +63,17 @@ async function main(): Promise<void> {
       await runForeground(resolveForegroundDir());
       return;
     default:
+      if (await isServiceActive()) {
+        console.log("Pigent already running.");
+        console.log("Commands: pigent status, pigent logs, pigent restart, pigent update");
+        process.exit(0);
+      }
       await installAndStartService(appDir);
   }
 }
 
 async function installAndStartService(targetDir: string): Promise<void> {
-  await ensureConfiguredApp(targetDir, true);
+  await ensureConfiguredApp(targetDir, needsSetup(targetDir));
 
   if (!(await hasSystemctl())) {
     console.log("[pigent] systemd user service unavailable; running in foreground");
@@ -89,6 +94,7 @@ async function installAndStartService(targetDir: string): Promise<void> {
   console.log("  pigent stop");
   console.log("  pigent restart");
   console.log("  pigent update");
+  process.exit(0);
 }
 
 async function startService(targetDir: string): Promise<void> {
@@ -98,6 +104,7 @@ async function startService(targetDir: string): Promise<void> {
   }
 
   await systemctl("start");
+  process.exit(0);
 }
 
 async function updateApp(targetDir: string): Promise<void> {
@@ -117,6 +124,7 @@ async function updateApp(targetDir: string): Promise<void> {
     await systemctl("enable", true, `${serviceName}.service`);
     await systemctl("restart");
     console.log("[pigent] updated and restarted service");
+    process.exit(0);
   } else {
     console.log("[pigent] updated. Run `pigent run` to start foreground daemon.");
   }
@@ -259,6 +267,15 @@ async function hasSystemctl(): Promise<boolean> {
   return result.exitCode === 0;
 }
 
+async function isServiceActive(): Promise<boolean> {
+  if (!(await hasSystemctl())) return false;
+  const proc = Bun.spawn(["systemctl", "--user", "is-active", "--quiet", `${serviceName}.service`], {
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+  return (await proc.exited) === 0;
+}
+
 function servicePath(): string {
   return join(homedir(), ".config", "systemd", "user", `${serviceName}.service`);
 }

package/src/daemon/AgentDaemon.ts

@@ -1,3 +1,4 @@
+import { AgentRegistry } from "../agents/AgentRegistry";
 import { AgentRunner } from "../agents/AgentRunner";
 import { BotCommandHandler } from "../agents/BotCommandHandler";
 import { MessageRouter } from "../agents/MessageRouter";
@@ -13,6 +14,7 @@ export class AgentDaemon {
   private running = false;
   private readonly adapters: ChannelAdapter[];
   private readonly commands: BotCommandHandler;
+  private readonly registry: AgentRegistry;
   private readonly router: MessageRouter;
   private readonly runner: AgentRunner;
 
@@ -21,9 +23,10 @@ export class AgentDaemon {
     private readonly repositories: Repositories,
   ) {
     this.adapters = createAdapters(repositories);
-    this.commands = new BotCommandHandler(config, repositories);
-    this.router = new MessageRouter(repositories);
-    this.runner = new AgentRunner(config, repositories);
+    this.registry = new AgentRegistry(config, repositories);
+    this.commands = new BotCommandHandler(this.registry, repositories);
+    this.router = new MessageRouter(repositories, this.registry);
+    this.runner = new AgentRunner(this.registry, repositories);
   }
 
   static async create(): Promise<AgentDaemon> {
@@ -43,8 +46,8 @@ export class AgentDaemon {
     }
 
     logger.info("pigent daemon started", {
-      agents: this.config.agents.length,
-      profiles: this.config.profiles.length,
+      agents: this.registry.listAgents().length,
+      profiles: this.registry.listProfiles().length,
       telegramChats: this.config.telegramChats.length,
       adapters: this.adapters.map((adapter) => adapter.id),
     });
@@ -63,9 +66,7 @@ export class AgentDaemon {
   }
 
   private async syncConfiguredState(): Promise<void> {
-    for (const agent of this.config.agents) {
-      await this.repositories.agents.upsertLoadedAgent(agent);
-    }
+    await this.registry.syncConfiguredAgents();
 
     for (const chat of this.config.telegramChats) {
       await this.repositories.telegram.upsertConfiguredChat(chat);
@@ -125,7 +126,7 @@ export class AgentDaemon {
     if (message.channel !== "telegram") return;
     if (process.env.PIGENT_AUTO_SETUP_CHATS !== "1") return;
 
-    const defaultAgentId = process.env.PIGENT_AUTO_SETUP_DEFAULT_AGENT ?? this.config.agents[0]?.id;
+    const defaultAgentId = process.env.PIGENT_AUTO_SETUP_DEFAULT_AGENT ?? this.registry.defaultAgentId();
     if (!defaultAgentId) return;
 
     await this.repositories.telegram.autoConfigureChat(message, defaultAgentId);

package/src/db/repositories/HeartbeatRepository.ts

@@ -0,0 +1,129 @@
+import { and, desc, eq, gte, isNull } from "drizzle-orm";
+import { nanoid } from "nanoid";
+import type { DbClient } from "../client";
+import { heartbeats, type HeartbeatRow } from "../schema";
+
+export type HeartbeatStatus = "pending" | "running" | "noop" | "notified" | "failed";
+
+export type CreateHeartbeatInput = {
+  agentId: string;
+  sessionId?: string | null;
+  prompt: string;
+  status?: Extract<HeartbeatStatus, "pending" | "running">;
+  startedAt?: number | null;
+};
+
+export type FinishHeartbeatInput = {
+  result?: string | null;
+  error?: string | null;
+  finishedAt?: number;
+};
+
+export class HeartbeatRepository {
+  constructor(private readonly db: DbClient) {}
+
+  async create(input: CreateHeartbeatInput): Promise<HeartbeatRow> {
+    const id = nanoid();
+    const now = Date.now();
+
+    await this.db.insert(heartbeats).values({
+      id,
+      agentId: input.agentId,
+      sessionId: input.sessionId ?? null,
+      status: input.status ?? "pending",
+      prompt: input.prompt,
+      result: null,
+      error: null,
+      startedAt: input.startedAt ?? null,
+      finishedAt: null,
+      createdAt: now,
+    });
+
+    const row = await this.findById(id);
+    if (!row) throw new Error(`failed to create heartbeat ${id}`);
+
+    return row;
+  }
+
+  async markRunning(id: string, startedAt = Date.now()): Promise<HeartbeatRow> {
+    await this.db
+      .update(heartbeats)
+      .set({
+        status: "running",
+        startedAt,
+      })
+      .where(eq(heartbeats.id, id));
+
+    return this.requireById(id);
+  }
+
+  async markNoop(id: string, input: FinishHeartbeatInput = {}): Promise<HeartbeatRow> {
+    return this.finish(id, "noop", input);
+  }
+
+  async markNotified(id: string, input: FinishHeartbeatInput = {}): Promise<HeartbeatRow> {
+    return this.finish(id, "notified", input);
+  }
+
+  async markFailed(id: string, input: FinishHeartbeatInput): Promise<HeartbeatRow> {
+    return this.finish(id, "failed", input);
+  }
+
+  async findById(id: string): Promise<HeartbeatRow | null> {
+    const row = await this.db.query.heartbeats.findFirst({
+      where: eq(heartbeats.id, id),
+    });
+
+    return row ?? null;
+  }
+
+  async findLatest(agentId: string, sessionId?: string | null): Promise<HeartbeatRow | null> {
+    const sessionPredicate = sessionId ? eq(heartbeats.sessionId, sessionId) : isNull(heartbeats.sessionId);
+
+    const row = await this.db.query.heartbeats.findFirst({
+      where: and(eq(heartbeats.agentId, agentId), sessionPredicate),
+      orderBy: desc(heartbeats.createdAt),
+    });
+
+    return row ?? null;
+  }
+
+  async countRecentNotified(agentId: string, since: number, sessionId?: string | null): Promise<number> {
+    const sessionPredicate = sessionId ? eq(heartbeats.sessionId, sessionId) : isNull(heartbeats.sessionId);
+
+    const rows = await this.db.query.heartbeats.findMany({
+      where: and(
+        eq(heartbeats.agentId, agentId),
+        sessionPredicate,
+        eq(heartbeats.status, "notified"),
+        gte(heartbeats.finishedAt, since),
+      ),
+      columns: {
+        id: true,
+      },
+    });
+
+    return rows.length;
+  }
+
+  private async finish(id: string, status: Extract<HeartbeatStatus, "noop" | "notified" | "failed">, input: FinishHeartbeatInput): Promise<HeartbeatRow> {
+    await this.db
+      .update(heartbeats)
+      .set({
+        status,
+        result: input.result ?? null,
+        error: input.error ?? null,
+        finishedAt: input.finishedAt ?? Date.now(),
+      })
+      .where(eq(heartbeats.id, id));
+
+    return this.requireById(id);
+  }
+
+  private async requireById(id: string): Promise<HeartbeatRow> {
+    const row = await this.findById(id);
+    if (!row) throw new Error(`heartbeat not found ${id}`);
+
+    return row;
+  }
+}

package/src/db/repositories/index.ts

@@ -1,5 +1,6 @@
 import { db } from "../client";
 import { AgentRepository } from "./AgentRepository";
+import { HeartbeatRepository } from "./HeartbeatRepository";
 import { MessageRepository } from "./MessageRepository";
 import { RuntimeKvRepository } from "./RuntimeKvRepository";
 import { SessionRepository } from "./SessionRepository";
@@ -10,6 +11,7 @@ export type Repositories = ReturnType<typeof createRepositories>;
 export function createRepositories(dbClient = db) {
   return {
     agents: new AgentRepository(dbClient),
+    heartbeats: new HeartbeatRepository(dbClient),
     messages: new MessageRepository(dbClient),
     runtimeKv: new RuntimeKvRepository(dbClient),
     sessions: new SessionRepository(dbClient),