jeopi-cli 16.6.14 → 16.6.17

package/dist/types/cli/messenger-cli.d.ts

@@ -1,10 +1,18 @@
-export declare const MESSENGER_ACTIONS: readonly ["check", "run"];
+export declare const MESSENGER_ACTIONS: readonly ["check", "run", "setup"];
 export type MessengerAction = (typeof MESSENGER_ACTIONS)[number];
+export interface MessengerSetupFlags {
+    channel?: string[];
+    user?: string[];
+    tools?: string;
+    artifacts?: boolean;
+    service?: boolean;
+    "no-dm"?: boolean;
+}
 export interface MessengerCommandArgs {
     action: MessengerAction;
     flags: {
         config: string;
-    };
+    } & MessengerSetupFlags;
 }
 /**
  * Check is deliberately local-only: it never starts a transport. The gateway process itself never loads the

package/dist/types/commands/messenger.d.ts

@@ -5,13 +5,33 @@ export default class Messenger extends Command {
         action: import("jeopi-utils/cli").ArgDescriptor & {
             description: string;
             required: false;
-            options: ("check" | "run")[];
+            options: ("check" | "run" | "setup")[];
         };
     };
     static flags: {
         config: import("jeopi-utils/cli").FlagDescriptor<"string"> & {
             description: string;
         };
+        channel: import("jeopi-utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+            multiple: true;
+        };
+        user: import("jeopi-utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+            multiple: true;
+        };
+        tools: import("jeopi-utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        artifacts: import("jeopi-utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
+        service: import("jeopi-utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
+        "no-dm": import("jeopi-utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
     };
     static examples: string[];
     run(): Promise<void>;

package/dist/types/messenger/discord-setup.d.ts

@@ -0,0 +1,48 @@
+import { installMessengerService } from "./service";
+export declare const DISCORD_TOKEN_ENV = "JEOPI_DISCORD_BOT_TOKEN";
+/** What the gateway needs in a request channel: read, reply, react, attach, and open request threads. */
+export declare const DISCORD_REQUIRED_PERMISSIONS: ReadonlyArray<readonly [name: string, bit: bigint]>;
+export interface DiscordSetupIO {
+    readonly interactive: boolean;
+    say(line: string): void;
+    ask(question: string): Promise<string>;
+    askSecret(question: string): Promise<string>;
+}
+export interface DiscordSetupOptions {
+    /** messenger.json to create or update; its directory becomes the private profile directory. */
+    configPath: string;
+    channelIds?: string[];
+    userIds?: string[];
+    toolNames?: string[];
+    artifacts?: boolean;
+    service?: boolean;
+    /** Open the owner's DM channel, allow it, and send one test message. Default true. */
+    dmTest?: boolean;
+    inviteWaitMs?: number;
+}
+export interface DiscordSetupDeps {
+    fetch?: typeof fetch;
+    WebSocket?: typeof WebSocket;
+    env?: Record<string, string | undefined>;
+    sleep?: (ms: number) => Promise<void>;
+    /** argv that starts this jeopi build; defaults to the running runtime and entry. */
+    jeopiCommand?: string[];
+    installService?: typeof installMessengerService;
+}
+export interface DiscordSetupResult {
+    configPath: string;
+    botName: string;
+    applicationId: string;
+    inviteUrl: string;
+    allowedUserIds: string[];
+    allowedChannelIds: string[];
+    runScript: string;
+    service?: string;
+}
+export declare function discordInviteUrl(applicationId: string): string;
+/** Discord's documented order: @everyone and role bits, Administrator, then @everyone/role/member overwrites. */
+export declare function discordChannelPermissions(guild: Record<string, unknown>, memberRoleIds: string[], channel: Record<string, unknown>, botId: string): bigint;
+/** The token is read from the 0600 file at launch, so it never lands in this script or a service definition. */
+export declare function discordRunScript(command: string[], configName: string, tokenEnv: string, envPath: string): string;
+/** Create or repair a Discord messenger profile with as few manual steps as Discord allows. */
+export declare function setupDiscordMessenger(options: DiscordSetupOptions, io: DiscordSetupIO, deps?: DiscordSetupDeps): Promise<DiscordSetupResult>;

package/dist/types/messenger/discord.d.ts

@@ -1,4 +1,6 @@
 import type { MessengerAdapter, MessengerPlatformConfig, MessengerTransportDeps } from "./types";
+export declare const DISCORD_API = "https://discord.com/api/v10";
+export declare const DISCORD_GATEWAY_INTENTS: number;
 export interface DiscordClock {
     /** Schedule once and return an idempotent cancellation function. */
     schedule(callback: () => void, delayMs: number): () => void;
@@ -7,4 +9,5 @@ export interface DiscordClock {
 export interface DiscordTransportDeps extends MessengerTransportDeps {
     clock?: DiscordClock;
 }
+export declare function discordGatewayUrl(value: unknown): string;
 export declare function createDiscordAdapter(config: MessengerPlatformConfig, env?: Record<string, string | undefined>, deps?: DiscordTransportDeps): MessengerAdapter;

package/dist/types/messenger/service.d.ts

@@ -0,0 +1,19 @@
+/** A per-user background service that keeps one messenger profile's gateway running. */
+export interface MessengerServicePlan {
+    /** Stable service name derived from the profile directory. */
+    label: string;
+    /** Profile directory: working directory and home of the run script and log. */
+    directory: string;
+    runScript: string;
+    logFile: string;
+}
+export declare function messengerServicePlan(directory: string, runScript: string): MessengerServicePlan;
+/** launchd job: starts at login, restarts after a crash (throttled), logs to the profile directory. */
+export declare function launchdPlist(plan: MessengerServicePlan): string;
+/** systemd --user unit with the same lifecycle as the launchd job. */
+export declare function systemdUnit(plan: MessengerServicePlan): string;
+/**
+ * Install (or replace) and start the service, then confirm the platform reports it running.
+ * Returns a one-line description of where it was installed.
+ */
+export declare function installMessengerService(plan: MessengerServicePlan, platform?: NodeJS.Platform, home?: string): Promise<string>;

package/dist/types/messenger/types.d.ts

@@ -24,11 +24,15 @@ export interface MessengerAdapter {
     send(message: MessengerMessage, text: string, signal?: AbortSignal): Promise<void>;
     prepare?(message: MessengerMessage, signal?: AbortSignal): Promise<MessengerMessage>;
     status?(message: MessengerMessage, status: "processing" | "success" | "failure", signal?: AbortSignal): Promise<void>;
+    /** Remove an in-progress status after cancellation without adding a terminal status. */
+    clearStatus?(message: MessengerMessage, signal?: AbortSignal): Promise<void>;
     /**
      * Show `text` (one sanitized line) as the request's single in-progress status, editing it in place on
      * later calls; `undefined` removes it. The gateway serializes and throttles calls per request.
      */
     activity?(message: MessengerMessage, text: string | undefined, signal?: AbortSignal): Promise<void>;
+    /** Forget request-local cosmetic activity state after the gateway finishes cleanup retries. */
+    releaseActivity?(message: MessengerMessage): void;
 }
 export interface MessengerPlatformConfig {
     tokenEnv: string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "jeopi-cli",
-	"version": "16.6.14",
+	"version": "16.6.17",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/akillness/jeopi",
 	"author": "Can Boluk",
@@ -57,17 +57,17 @@
 		"@agentclientprotocol/sdk": "0.25.0",
 		"@babel/parser": "^7.29.7",
 		"@mozilla/readability": "^0.6.0",
-		"jeopi-hashline": "16.6.14",
-		"jeopi-stats": "16.6.14",
-		"jeopi-agent-core": "16.6.14",
-		"jeopi-ai": "16.6.14",
-		"jeopi-catalog": "16.6.14",
-		"jeopi-mnemopi": "16.6.14",
-		"jeopi-natives": "16.6.14",
-		"jeopi-tui": "16.6.14",
-		"jeopi-utils": "16.6.14",
-		"jeopi-wire": "16.6.14",
-		"jeopi-snapcompact": "16.6.14",
+		"jeopi-hashline": "16.6.17",
+		"jeopi-stats": "16.6.17",
+		"jeopi-agent-core": "16.6.17",
+		"jeopi-ai": "16.6.17",
+		"jeopi-catalog": "16.6.17",
+		"jeopi-mnemopi": "16.6.17",
+		"jeopi-natives": "16.6.17",
+		"jeopi-tui": "16.6.17",
+		"jeopi-utils": "16.6.17",
+		"jeopi-wire": "16.6.17",
+		"jeopi-snapcompact": "16.6.17",
 		"@opentelemetry/api": "^1.9.1",
 		"@opentelemetry/context-async-hooks": "^2.7.1",
 		"@opentelemetry/exporter-trace-otlp-proto": "^0.218.0",

package/src/cli/messenger-cli.ts

@@ -1,21 +1,92 @@
+import { createInterface } from "node:readline/promises";
+import { Writable } from "node:stream";
 import { loadMessengerConfig, validateMessengerEnvironment } from "../messenger/config";
 import { createDiscordAdapter } from "../messenger/discord";
+import { type DiscordSetupIO, type DiscordSetupResult, setupDiscordMessenger } from "../messenger/discord-setup";
 import { createMessengerGateway } from "../messenger/gateway";
 import { createMessengerSessionPool, type MessengerSessionPool } from "../messenger/session-pool";
 import { createSlackAdapter } from "../messenger/slack";
 import { createTelegramAdapter } from "../messenger/telegram";
 import type { MessengerAdapter, MessengerConfig } from "../messenger/types";
 
-export const MESSENGER_ACTIONS = ["check", "run"] as const;
+export const MESSENGER_ACTIONS = ["check", "run", "setup"] as const;
 export type MessengerAction = (typeof MESSENGER_ACTIONS)[number];
+export interface MessengerSetupFlags {
+	channel?: string[];
+	user?: string[];
+	tools?: string;
+	artifacts?: boolean;
+	service?: boolean;
+	"no-dm"?: boolean;
+}
 export interface MessengerCommandArgs {
 	action: MessengerAction;
-	flags: { config: string };
+	flags: { config: string } & MessengerSetupFlags;
 }
 
 /** Conversations answered at once; each conversation runs in its own session process. */
 const MESSENGER_CONCURRENCY = 4;
 
+function terminalSetupIO(): DiscordSetupIO {
+	const question = async (prompt: string, hidden: boolean): Promise<string> => {
+		// Hidden input: readline still reads keys but echoes into a sink.
+		const output = hidden ? new Writable({ write: (_chunk, _encoding, done) => done() }) : process.stdout;
+		if (hidden) process.stdout.write(prompt);
+		const rl = createInterface({ input: process.stdin, output, terminal: true });
+		try {
+			return await rl.question(hidden ? "" : prompt);
+		} finally {
+			rl.close();
+			if (hidden) process.stdout.write("\n");
+		}
+	};
+	return {
+		interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+		say: line => process.stdout.write(`${line}\n`),
+		ask: prompt => question(prompt, false),
+		askSecret: prompt => question(prompt, true),
+	};
+}
+
+function splitList(values: string[] | undefined): string[] | undefined {
+	const items = values
+		?.flatMap(value => value.split(","))
+		.map(value => value.trim())
+		.filter(Boolean);
+	return items?.length ? items : undefined;
+}
+
+async function runSetup(flags: MessengerCommandArgs["flags"]): Promise<void> {
+	const io = terminalSetupIO();
+	let result: DiscordSetupResult;
+	try {
+		result = await setupDiscordMessenger(
+			{
+				configPath: flags.config,
+				channelIds: splitList(flags.channel),
+				userIds: splitList(flags.user),
+				toolNames: flags.tools === undefined ? undefined : (splitList([flags.tools]) ?? []),
+				artifacts: flags.artifacts,
+				service: flags.service,
+				dmTest: !flags["no-dm"],
+			},
+			io,
+		);
+	} catch (error) {
+		// Setup errors are written for the user and never carry the token.
+		process.stderr.write(`Discord setup stopped: ${error instanceof Error ? error.message : String(error)}\n`);
+		process.exitCode = 1;
+		return;
+	}
+	io.say("");
+	io.say(`Discord messenger ready: ${result.configPath}`);
+	io.say(`  allowed users: ${result.allowedUserIds.join(", ")}`);
+	io.say(`  allowed channels: ${result.allowedChannelIds.join(", ")}`);
+	io.say(`  invite (other servers): ${result.inviteUrl}`);
+	io.say(result.service ? `  service: ${result.service}` : `  start: ${result.runScript}  (or rerun with --service)`);
+	io.say("Test: DM the bot, and mention it in the request channel; it replies in a thread.");
+}
+
 /**
  * Check is deliberately local-only: it never starts a transport. The gateway process itself never loads the
  * SDK; every conversation's AgentSession lives in its own session process.
@@ -23,6 +94,10 @@ const MESSENGER_CONCURRENCY = 4;
 export async function runMessengerCommand(cmd: MessengerCommandArgs): Promise<void> {
 	if (!MESSENGER_ACTIONS.includes(cmd.action)) throw new Error("Unknown messenger action");
 	if (!cmd.flags.config) throw new Error("Messenger requires --config <file>");
+	if (cmd.action === "setup") {
+		await runSetup(cmd.flags);
+		return;
+	}
 	// Do not echo parse errors, paths, configuration values, or environment secrets.
 	let config: MessengerConfig;
 	try {

package/src/commands/messenger.ts

@@ -3,7 +3,7 @@ import { Args, Command, Flags, renderCommandHelp } from "jeopi-utils/cli";
 import { MESSENGER_ACTIONS, type MessengerAction, runMessengerCommand } from "../cli/messenger-cli";
 
 export default class Messenger extends Command {
-	static description = "Run authorized Discord, Telegram, and Slack text bots";
+	static description = "Set up and run authorized Discord, Telegram, and Slack text bots";
 
 	static args = {
 		action: Args.string({ description: "Sub-command", required: false, options: [...MESSENGER_ACTIONS] }),
@@ -11,9 +11,22 @@ export default class Messenger extends Command {
 
 	static flags = {
 		config: Flags.string({ description: "Path to messenger JSON configuration" }),
+		channel: Flags.string({
+			description: "setup: Discord request channel or thread ID (repeatable)",
+			multiple: true,
+		}),
+		user: Flags.string({
+			description: "setup: allowed Discord user ID (default: the application owner)",
+			multiple: true,
+		}),
+		tools: Flags.string({ description: "setup: comma-separated tools for remote chats (default: none)" }),
+		artifacts: Flags.boolean({ description: "setup: enable Discord file exchange in ./artifacts" }),
+		service: Flags.boolean({ description: "setup: run the gateway as a login service (launchd or systemd --user)" }),
+		"no-dm": Flags.boolean({ description: "setup: skip opening and testing the owner's DM channel" }),
 	};
 
 	static examples = [
+		"jeopi messenger setup --config ~/.jeopi/discord/messenger.json --service",
 		"jeopi messenger check --config ./messenger.json",
 		"jeopi messenger run --config ./messenger.json",
 	];
@@ -25,6 +38,17 @@ export default class Messenger extends Command {
 			return;
 		}
 		if (!flags.config) throw new Error("Messenger requires --config <file>");
-		await runMessengerCommand({ action: args.action as MessengerAction, flags: { config: flags.config } });
+		await runMessengerCommand({
+			action: args.action as MessengerAction,
+			flags: {
+				config: flags.config,
+				channel: flags.channel,
+				user: flags.user,
+				tools: flags.tools,
+				artifacts: flags.artifacts,
+				service: flags.service,
+				"no-dm": flags["no-dm"],
+			},
+		});
 	}
 }