@nettee/beacon 0.1.0

package/dist/state/trigger-store.js

@@ -0,0 +1,234 @@
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, mkdir, open, readdir, readFile, rename, } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { failureCodes, } from "../domain/types.js";
+const timestamp = z.string().datetime({ offset: true });
+const failureSchema = z
+    .object({ code: z.enum(failureCodes), summary: z.string().min(1).max(4096) })
+    .strict();
+const targetSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("reply"), messageId: z.string().min(1) }).strict(),
+    z.object({ kind: z.literal("chat"), chatId: z.string().min(1) }).strict(),
+    z.object({ kind: z.literal("local_stdout") }).strict(),
+]);
+const messageSchema = z
+    .object({
+    messageId: z.string().min(1),
+    messageType: z.string().min(1),
+    senderType: z.string().min(1),
+    senderId: z.string().min(1).optional(),
+    content: z.unknown(),
+})
+    .strict();
+const inputSchema = z.discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.literal("feishu_message"),
+        eventId: z.string().min(1),
+        chatType: z.enum(["p2p", "group"]),
+        quotedMessages: z.array(messageSchema),
+        currentMessage: messageSchema,
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("schedule"),
+        scheduleId: z.string().min(1),
+        scheduledFor: timestamp,
+        text: z.string().min(1),
+    })
+        .strict(),
+    z.object({ kind: z.literal("manual"), text: z.string().min(1) }).strict(),
+]);
+const runSchema = z
+    .object({
+    runId: z.string().min(1),
+    state: z.enum(["queued", "starting", "running", "succeeded", "failed"]),
+    queuedAt: timestamp,
+    startedAt: timestamp.optional(),
+    finishedAt: timestamp.optional(),
+    provider: z.string().min(1),
+    model: z.string().min(1),
+    workspace: z.string().min(1),
+    promptDigest: z.string().regex(/^[a-f0-9]{64}$/),
+    failure: failureSchema.optional(),
+})
+    .strict();
+const outcomeSchema = z
+    .object({
+    origin: z.enum(["agent", "beacon_failure"]),
+    text: z.string().min(1),
+    submittedAt: timestamp,
+})
+    .strict();
+const deliverySchema = z
+    .object({
+    deliveryId: z.string().min(1),
+    target: targetSchema,
+    state: z.enum(["pending", "delivering", "delivered", "failed"]),
+    startedAt: timestamp.optional(),
+    finishedAt: timestamp.optional(),
+    providerRequestId: z.string().min(1).optional(),
+    failure: failureSchema.optional(),
+})
+    .strict();
+const triggerRecordSchema = z
+    .object({
+    version: z.literal(1),
+    triggerKey: z.string().regex(/^[a-f0-9]{64}$/),
+    triggerId: z.string().min(1),
+    profileId: z.string().min(1),
+    sourceKey: z.array(z.string().min(1)).min(2),
+    acceptedAt: timestamp,
+    target: targetSchema,
+    input: inputSchema.optional(),
+    ingress: z.record(z.string(), z.unknown()).optional(),
+    run: runSchema.optional(),
+    finalOutcome: outcomeSchema.optional(),
+    delivery: deliverySchema.optional(),
+})
+    .strict();
+function keyFor(profileId, sourceKey) {
+    return createHash("sha256")
+        .update(JSON.stringify(["beacon-trigger-v1", profileId, ...sourceKey]))
+        .digest("hex");
+}
+function validateRecord(value) {
+    const record = triggerRecordSchema.parse(value);
+    if (record.delivery && !record.finalOutcome) {
+        throw new Error("Trigger record with Delivery must contain a Final Outcome");
+    }
+    if (record.run?.state === "succeeded" &&
+        record.finalOutcome?.origin !== "agent") {
+        throw new Error("Succeeded Run must contain an Agent Final Outcome");
+    }
+    if (record.run?.state === "failed" && !record.run.failure) {
+        throw new Error("Failed Run must contain failure details");
+    }
+    return record;
+}
+export class TriggerStore {
+    profileId;
+    root;
+    constructor(profileDirectory, profileId) {
+        this.profileId = profileId;
+        this.root = join(profileDirectory, "state", "triggers");
+    }
+    recordPath(triggerKey) {
+        return join(this.root, triggerKey, "record.json");
+    }
+    async prepare() {
+        await mkdir(this.root, { recursive: true, mode: 0o700 });
+        await chmod(join(this.root, ".."), 0o700);
+        await chmod(this.root, 0o700);
+    }
+    async read(triggerKey) {
+        const path = this.recordPath(triggerKey);
+        let raw;
+        try {
+            raw = await readFile(path, "utf8");
+        }
+        catch (error) {
+            throw new Error(`Cannot read Trigger record at ${path}`, {
+                cause: error,
+            });
+        }
+        try {
+            return validateRecord(JSON.parse(raw));
+        }
+        catch (error) {
+            throw new Error(`Cannot parse Trigger record at ${path}`, {
+                cause: error,
+            });
+        }
+    }
+    async readConcurrentClaim(triggerKey) {
+        for (let attempt = 0; attempt < 100; attempt += 1) {
+            try {
+                return await this.read(triggerKey);
+            }
+            catch (error) {
+                const cause = error instanceof Error
+                    ? error.cause
+                    : undefined;
+                if (cause?.code !== "ENOENT")
+                    throw error;
+                await new Promise((resolve) => setTimeout(resolve, 5));
+            }
+        }
+        return this.read(triggerKey);
+    }
+    async write(triggerKey, record) {
+        const validated = validateRecord(record);
+        const directory = join(this.root, triggerKey);
+        const temporary = join(directory, `.record-${randomUUID()}.tmp`);
+        const handle = await open(temporary, "wx", 0o600);
+        try {
+            await handle.writeFile(`${JSON.stringify(validated, null, 2)}\n`, "utf8");
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temporary, this.recordPath(triggerKey));
+        const directoryHandle = await open(directory, "r");
+        try {
+            await directoryHandle.sync();
+        }
+        finally {
+            await directoryHandle.close();
+        }
+    }
+    async claim(request) {
+        if (request.sourceKey.length < 2 ||
+            request.sourceKey.some((part) => !part)) {
+            throw new Error("Trigger source key must contain at least two non-empty parts");
+        }
+        await this.prepare();
+        const triggerKey = keyFor(this.profileId, request.sourceKey);
+        const directory = join(this.root, triggerKey);
+        try {
+            await mkdir(directory, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code === "EEXIST") {
+                return {
+                    created: false,
+                    record: await this.readConcurrentClaim(triggerKey),
+                };
+            }
+            throw new Error(`Cannot claim Trigger ${triggerKey}`, { cause: error });
+        }
+        const record = {
+            version: 1,
+            triggerKey,
+            triggerId: `trg_${triggerKey.slice(0, 24)}`,
+            profileId: this.profileId,
+            sourceKey: [...request.sourceKey],
+            acceptedAt: (request.acceptedAt ?? new Date()).toISOString(),
+            target: request.target,
+            ...(request.ingress ? { ingress: request.ingress } : {}),
+        };
+        await this.write(triggerKey, record);
+        return { created: true, record };
+    }
+    async update(triggerKey, transform) {
+        const current = await this.read(triggerKey);
+        const next = transform(structuredClone(current));
+        if (next.triggerKey !== triggerKey || next.profileId !== this.profileId) {
+            throw new Error("Trigger identity cannot change during update");
+        }
+        await this.write(triggerKey, next);
+        return next;
+    }
+    async list() {
+        await this.prepare();
+        const entries = await readdir(this.root, { withFileTypes: true });
+        const records = await Promise.all(entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => this.read(entry.name)));
+        return records.sort((left, right) => left.acceptedAt.localeCompare(right.acceptedAt) ||
+            left.triggerId.localeCompare(right.triggerId));
+    }
+}

package/dist/version.js

@@ -0,0 +1,9 @@
+import { createRequire } from "node:module";
+const metadata = createRequire(import.meta.url)("../package.json");
+const version = typeof metadata === "object" && metadata !== null
+    ? metadata.version
+    : undefined;
+if (typeof version !== "string" || !version) {
+    throw new Error("Beacon package metadata must contain a version");
+}
+export const packageVersion = version;

package/examples/config.yaml

@@ -0,0 +1,12 @@
+version: 1
+profiles_directory: profiles
+pi:
+  executable: /ABSOLUTE/PATH/TO/pi
+  coding_agent_directory: /Users/USERNAME/.pi/agent
+runs:
+  max_concurrent: 2
+  max_queued: 100
+  timeout_seconds: 1800
+  terminate_grace_seconds: 5
+scheduler:
+  max_occurrences_per_reconciliation: 1000

package/examples/profiles/example/profile.yaml

@@ -0,0 +1,13 @@
+prompt: prompt.md
+workspace: /ABSOLUTE/PATH/TO/WORKSPACE
+runtime: pi
+model:
+  provider: REPLACE_WITH_PI_PROVIDER
+  id: REPLACE_WITH_PI_MODEL
+schedules:
+  - id: weekday-brief
+    cron: "0 9 * * 1-5"
+    timezone: Asia/Shanghai
+    input: Prepare the weekday brief.
+    delivery:
+      chat_id: REPLACE_WITH_DIRECT_OR_GROUP_CHAT_ID

package/examples/profiles/example/prompt.md

@@ -0,0 +1 @@
+You are the configured Beacon Profile. Work only within the provided workspace and return a concise, user-facing result through the required Final Outcome tool.

package/examples/secrets.json.example

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "profiles": {
+    "example": {
+      "feishu": {
+        "app_id": "cli_0123456789abcdef",
+        "app_secret": "REPLACE_ME"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@nettee/beacon",
+  "version": "0.1.0",
+  "description": "A single-host bridge from messaging and schedules to isolated agent runs",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nettee/beacon.git"
+  },
+  "homepage": "https://github.com/nettee/beacon#readme",
+  "bugs": {
+    "url": "https://github.com/nettee/beacon/issues"
+  },
+  "keywords": [
+    "agent",
+    "cli",
+    "feishu",
+    "automation"
+  ],
+  "type": "module",
+  "bin": {
+    "beacon": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "deploy/io.nettee.beacon.plist.example",
+    "examples/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "biome check .",
+    "dev": "tsx src/cli.ts",
+    "e2e:message": "tsc -p tsconfig.e2e.json --noEmit && pnpm build && tsx --test e2e/message/*.e2e.test.ts",
+    "prebuild": "node scripts/clean-dist.mjs",
+    "prepack": "pnpm build",
+    "test": "tsx --test src/*.test.ts src/**/*.test.ts scripts/*.test.mjs",
+    "test:package": "node scripts/test-package.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "packageManager": "pnpm@10.33.2",
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@larksuiteoapi/node-sdk": "^1.58.0",
+    "cron-parser": "^5.10.0",
+    "yaml": "^2.9.1",
+    "zod": "^4.1.8"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.13",
+    "@types/node": "^24.3.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2"
+  }
+}