@kbve/droid 0.1.1 → 0.1.2

package/src/lib/agents/config.ts

@@ -0,0 +1,83 @@
+import { addToast } from '../state/toasts';
+import type { ToastSeverity } from '../types/ui-event-types';
+
+export interface AgentsNotice {
+	message: string;
+	severity: ToastSeverity;
+	duration?: number;
+}
+
+export interface AgentsSession {
+	accessToken: string | null;
+	providerToken: string | null;
+}
+
+export interface AgentsConfig {
+	supabaseUrl: string;
+	discordBotClientId?: string;
+	discordClientId?: string;
+
+	loadSession(): Promise<AgentsSession>;
+	refreshSession(): Promise<string | null>;
+
+	getDiscordProviderToken(): string | null;
+	clearDiscordProviderToken(): void;
+
+	signInWithDiscord(): Promise<void>;
+
+	notify?(notice: AgentsNotice): void;
+}
+
+export interface ResolvedAgentsConfig extends Required<
+	Omit<AgentsConfig, 'notify'>
+> {
+	notify(notice: AgentsNotice): void;
+}
+
+function defaultNotify(notice: AgentsNotice): void {
+	addToast({
+		id: `agents-${notice.severity}-${Date.now()}`,
+		message: notice.message,
+		severity: notice.severity,
+		duration: notice.duration ?? 3500,
+	});
+}
+
+export function resolveAgentsConfig(
+	config: AgentsConfig,
+): ResolvedAgentsConfig {
+	return {
+		supabaseUrl: config.supabaseUrl.replace(/\/$/, ''),
+		discordBotClientId: config.discordBotClientId ?? '',
+		discordClientId: config.discordClientId ?? '',
+		loadSession: config.loadSession,
+		refreshSession: config.refreshSession,
+		getDiscordProviderToken: config.getDiscordProviderToken,
+		clearDiscordProviderToken: config.clearDiscordProviderToken,
+		signInWithDiscord: config.signInWithDiscord,
+		notify: config.notify ?? defaultNotify,
+	};
+}
+
+export interface AgentsEndpoints {
+	discordApiBase: string;
+	guildVault: string;
+	discordBootstrap: string;
+	discordBot: string;
+	ghAdmin: string;
+	ghBackfill: string;
+	ghWebhookBase: string;
+}
+
+export function buildEndpoints(supabaseUrl: string): AgentsEndpoints {
+	const base = supabaseUrl.replace(/\/$/, '');
+	return {
+		discordApiBase: 'https://discord.com/api/v10',
+		guildVault: `${base}/functions/v1/guild-vault`,
+		discordBootstrap: `${base}/functions/v1/discord-bootstrap`,
+		discordBot: `${base}/functions/v1/discord-bot`,
+		ghAdmin: `${base}/functions/v1/gh-admin`,
+		ghBackfill: `${base}/functions/v1/gh-backfill`,
+		ghWebhookBase: `${base}/functions/v1/gh-webhook`,
+	};
+}

package/src/lib/agents/constants.ts

@@ -0,0 +1,11 @@
+export const GUILDS_CACHE_KEY = 'kbve:agents:owned_guilds_cache:v1';
+export const TOKENS_CACHE_KEY = 'kbve:agents:tokens_cache:v1';
+
+export const GUILDS_CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+export const GUILDS_LIVE_TTL_MS = 60 * 1000;
+export const TOKENS_CACHE_TTL_MS = 60 * 1000;
+export const CHANNELS_CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+export const BOT_MEMBERSHIP_CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+export const INIT_DEDUP_MS = 30 * 1000;
+export const BOOTSTRAP_COOLDOWN_MS = 5 * 60 * 1000;
+export const FORCED_REFRESH_COOLDOWN_MS = 5 * 1000;

package/src/lib/agents/createAgents.ts

@@ -0,0 +1,62 @@
+import {
+	buildEndpoints,
+	resolveAgentsConfig,
+	type AgentsConfig,
+} from './config';
+import { createAgentsStore } from './state/atoms';
+import { createRuntime, type AgentsCtx } from './ctx';
+import { makeCallJson } from './client/callJson';
+import { makeCallGuildVault } from './client/callGuildVault';
+import { makeAuth } from './auth/init';
+import { makeGuilds } from './discord/guilds';
+import { makeDiscordBot } from './discord/bot';
+import { makeTokens } from './github/tokens';
+import { makeRepoConfig } from './github/repoConfig';
+import { makePat } from './github/pat';
+import { makeWebhook } from './github/webhook';
+import { makeBackfill } from './github/backfill';
+import { makeEvents } from './github/events';
+import type { AgentsApi } from './api-types';
+
+export function createAgents(config: AgentsConfig): AgentsApi {
+	const resolved = resolveAgentsConfig(config);
+	const store = createAgentsStore();
+	const runtime = createRuntime();
+
+	const ctx = {
+		config: resolved,
+		endpoints: buildEndpoints(resolved.supabaseUrl),
+		store,
+		runtime,
+		callJson: (() => {
+			throw new Error('agents: callJson used before init');
+		}) as AgentsCtx['callJson'],
+		callGuildVault: (() => {
+			throw new Error('agents: callGuildVault used before init');
+		}) as AgentsCtx['callGuildVault'],
+		resyncOwnedGuilds: async () => false,
+	} as AgentsCtx;
+
+	const api = { ...store } as AgentsApi;
+
+	ctx.callJson = makeCallJson(ctx);
+	ctx.callGuildVault = makeCallGuildVault(ctx);
+
+	const auth = makeAuth(ctx, api);
+	ctx.resyncOwnedGuilds = auth.resyncOwnedGuilds;
+
+	Object.assign(
+		api,
+		auth,
+		makeGuilds(ctx, api),
+		makeTokens(ctx, api),
+		makeRepoConfig(ctx, api),
+		makePat(ctx, api),
+		makeDiscordBot(ctx),
+		makeWebhook(ctx, api),
+		makeBackfill(ctx),
+		makeEvents(ctx, api),
+	);
+
+	return api;
+}

package/src/lib/agents/ctx.ts

@@ -0,0 +1,63 @@
+import type { AgentsEndpoints, ResolvedAgentsConfig } from './config';
+import type { AgentsStore } from './state/atoms';
+
+export type CallJsonResult<T> =
+	| { ok: true; data: T }
+	| { ok: false; error: string };
+
+export type CallVaultResult =
+	| { ok: true; body: unknown }
+	| { ok: false; error: string };
+
+export type CallJson = <T>(
+	url: string,
+	body: Record<string, unknown>,
+	opts?: { retriedAfterResync?: boolean },
+) => Promise<CallJsonResult<T>>;
+
+export type CallGuildVault = (
+	command: string,
+	accessToken: string,
+	extra: Record<string, unknown>,
+	opts?: { retriedAfterResync?: boolean },
+) => Promise<CallVaultResult>;
+
+export interface AgentsRuntime {
+	initPromise: Promise<void> | null;
+	lastInitAt: number;
+	lastGuildFetchAt: number;
+	guildsAbort: AbortController | null;
+	tokensInflight: Map<string, Promise<void>>;
+	tokensAbort: Map<string, AbortController>;
+	bootstrapInflight: Promise<boolean> | null;
+	lastBootstrapAt: number;
+	lastBootstrapOk: boolean;
+	refreshInflight: Promise<boolean> | null;
+	lastForcedRefreshAt: number;
+}
+
+export function createRuntime(): AgentsRuntime {
+	return {
+		initPromise: null,
+		lastInitAt: 0,
+		lastGuildFetchAt: 0,
+		guildsAbort: null,
+		tokensInflight: new Map(),
+		tokensAbort: new Map(),
+		bootstrapInflight: null,
+		lastBootstrapAt: 0,
+		lastBootstrapOk: false,
+		refreshInflight: null,
+		lastForcedRefreshAt: 0,
+	};
+}
+
+export interface AgentsCtx {
+	config: ResolvedAgentsConfig;
+	endpoints: AgentsEndpoints;
+	store: AgentsStore;
+	runtime: AgentsRuntime;
+	callJson: CallJson;
+	callGuildVault: CallGuildVault;
+	resyncOwnedGuilds: () => Promise<boolean>;
+}

package/src/lib/agents/discord/bot.ts

@@ -0,0 +1,169 @@
+import {
+	BOT_MEMBERSHIP_CACHE_TTL_MS,
+	CHANNELS_CACHE_TTL_MS,
+} from '../constants';
+import type { AgentsCtx } from '../ctx';
+import type { DiscordForumChannel, GuildChannels, Result } from '../types';
+
+export function makeDiscordBot(ctx: AgentsCtx) {
+	const { store, config, endpoints } = ctx;
+
+	async function ensureGuildChannelsLoaded(
+		guildId: string,
+		force = false,
+	): Promise<void> {
+		const cur = store.$guildChannels.get()[guildId];
+		const fresh =
+			!!cur && Date.now() - cur.cached_at < CHANNELS_CACHE_TTL_MS;
+		if (fresh && !force) return;
+		if (store.$guildChannelsLoading.get()[guildId]) return;
+		store.$guildChannelsLoading.set({
+			...store.$guildChannelsLoading.get(),
+			[guildId]: true,
+		});
+		store.$guildChannelsError.set({
+			...store.$guildChannelsError.get(),
+			[guildId]: null,
+		});
+		const r = await ctx.callJson<GuildChannels>(endpoints.discordBot, {
+			command: 'bot.list_channels',
+			server_id: guildId,
+		});
+		const loading = { ...store.$guildChannelsLoading.get() };
+		delete loading[guildId];
+		store.$guildChannelsLoading.set(loading);
+		if (!r.ok) {
+			store.$guildChannelsError.set({
+				...store.$guildChannelsError.get(),
+				[guildId]: r.error,
+			});
+			return;
+		}
+		store.$guildChannels.set({
+			...store.$guildChannels.get(),
+			[guildId]: {
+				forums: r.data.forums ?? [],
+				texts: r.data.texts ?? [],
+				cached_at: Date.now(),
+			},
+		});
+	}
+
+	async function ensureBotMembershipLoaded(
+		guildId: string,
+		force = false,
+	): Promise<void> {
+		const cur = store.$botMembership.get()[guildId];
+		const fresh =
+			!!cur && Date.now() - cur.cached_at < BOT_MEMBERSHIP_CACHE_TTL_MS;
+		if (fresh && !force) return;
+		if (store.$botMembershipLoading.get()[guildId]) return;
+		store.$botMembershipLoading.set({
+			...store.$botMembershipLoading.get(),
+			[guildId]: true,
+		});
+		store.$botMembershipError.set({
+			...store.$botMembershipError.get(),
+			[guildId]: null,
+		});
+		const r = await ctx.callJson<{ is_member: boolean }>(
+			endpoints.discordBot,
+			{ command: 'bot.is_member', server_id: guildId },
+		);
+		const loading = { ...store.$botMembershipLoading.get() };
+		delete loading[guildId];
+		store.$botMembershipLoading.set(loading);
+		if (!r.ok) {
+			store.$botMembershipError.set({
+				...store.$botMembershipError.get(),
+				[guildId]: r.error,
+			});
+			return;
+		}
+		store.$botMembership.set({
+			...store.$botMembership.get(),
+			[guildId]: {
+				isMember: !!r.data.is_member,
+				cached_at: Date.now(),
+			},
+		});
+	}
+
+	function invalidateBotMembership(guildId: string): void {
+		const m = { ...store.$botMembership.get() };
+		delete m[guildId];
+		store.$botMembership.set(m);
+	}
+
+	async function isBotMember(
+		guildId: string,
+	): Promise<
+		| { ok: true; isMember: boolean; joinedAt: string | null }
+		| { ok: false; error: string }
+	> {
+		const r = await ctx.callJson<{
+			is_member: boolean;
+			joined_at: string | null;
+		}>(endpoints.discordBot, {
+			command: 'bot.is_member',
+			server_id: guildId,
+		});
+		if (!r.ok) return r;
+		return {
+			ok: true,
+			isMember: !!r.data.is_member,
+			joinedAt: r.data.joined_at ?? null,
+		};
+	}
+
+	async function listForumChannels(
+		guildId: string,
+	): Promise<Result<{ channels: DiscordForumChannel[] }>> {
+		const r = await ctx.callJson<{ channels: DiscordForumChannel[] }>(
+			endpoints.discordBot,
+			{ command: 'bot.list_forum_channels', server_id: guildId },
+		);
+		if (!r.ok) return r;
+		return { ok: true, channels: r.data.channels ?? [] };
+	}
+
+	function buildInstallUrl(
+		clientId: string,
+		guildId?: string,
+	): string | null {
+		if (!/^[0-9]{17,20}$/.test(clientId)) return null;
+		const perms = '326417847872';
+		const scope = 'bot applications.commands';
+		const guildParam = guildId
+			? `&guild_id=${guildId}&disable_guild_select=true`
+			: '';
+		return `https://discord.com/oauth2/authorize?client_id=${clientId}&permissions=${perms}&scope=${encodeURIComponent(scope)}${guildParam}`;
+	}
+
+	function botInstallUrl(guildId?: string): string | null {
+		const clientId = config.discordBotClientId || config.discordClientId;
+		if (!clientId) return null;
+		return buildInstallUrl(clientId, guildId);
+	}
+
+	async function fetchBotInstallUrl(guildId: string): Promise<string | null> {
+		const fromEnv = botInstallUrl(guildId);
+		if (fromEnv) return fromEnv;
+		const r = await ctx.callJson<{ client_id: string }>(
+			endpoints.discordBot,
+			{ command: 'bot.install_info', server_id: guildId },
+		);
+		if (!r.ok || !r.data.client_id) return null;
+		return buildInstallUrl(r.data.client_id, guildId);
+	}
+
+	return {
+		ensureGuildChannelsLoaded,
+		ensureBotMembershipLoaded,
+		invalidateBotMembership,
+		isBotMember,
+		listForumChannels,
+		botInstallUrl,
+		fetchBotInstallUrl,
+	};
+}

package/src/lib/agents/discord/guilds.ts

@@ -0,0 +1,106 @@
+import { GUILDS_LIVE_TTL_MS } from '../constants';
+import { invalidateCachedTokens, saveCachedGuilds } from '../cache';
+import type { AgentsCtx } from '../ctx';
+import type { AgentsApi } from '../api-types';
+import type { DiscordGuild } from '../types';
+
+export function makeGuilds(ctx: AgentsCtx, api: AgentsApi) {
+	const { store, config, endpoints, runtime } = ctx;
+
+	function selectGuild(guildId: string): void {
+		const current = store.$selectedGuildId.get();
+		if (current === guildId) return;
+		store.$selectedGuildId.set(guildId);
+		void api.loadTokens(guildId);
+	}
+
+	async function loadOwnedGuilds(force = false): Promise<void> {
+		const providerToken = store.$providerToken.get();
+		if (!providerToken) return;
+
+		if (
+			!force &&
+			runtime.lastGuildFetchAt > 0 &&
+			Date.now() - runtime.lastGuildFetchAt < GUILDS_LIVE_TTL_MS &&
+			store.$guilds.get().length > 0
+		) {
+			return;
+		}
+
+		if (runtime.guildsAbort) runtime.guildsAbort.abort();
+		const abort = new AbortController();
+		runtime.guildsAbort = abort;
+
+		store.$guildsLoading.set(true);
+		store.$guildsError.set(null);
+
+		try {
+			const resp = await fetch(
+				`${endpoints.discordApiBase}/users/@me/guilds`,
+				{
+					headers: { Authorization: `Bearer ${providerToken}` },
+					signal: abort.signal,
+				},
+			);
+
+			if (resp.status === 401) {
+				store.$providerToken.set(null);
+				store.$guildsStale.set(true);
+				try {
+					config.clearDiscordProviderToken();
+				} catch {
+					/* non-fatal */
+				}
+				store.$guildsError.set(
+					'Discord session expired — guild list may be stale. Sign in with Discord to refresh.',
+				);
+				return;
+			}
+
+			if (!resp.ok) {
+				const body = await resp.text();
+				store.$guildsError.set(
+					`Discord API ${resp.status}: ${body.slice(0, 200)}`,
+				);
+				store.$guildsStale.set(true);
+				return;
+			}
+
+			const allGuilds = (await resp.json()) as DiscordGuild[];
+			const owned = allGuilds.filter((g) => g.owner === true);
+			store.$guilds.set(owned);
+			store.$guildsStale.set(false);
+			runtime.lastGuildFetchAt = Date.now();
+
+			const userId = store.$userId.get();
+			if (userId) saveCachedGuilds(userId, owned);
+
+			if (owned.length === 1) {
+				selectGuild(owned[0].id);
+			}
+		} catch (e) {
+			if (e instanceof DOMException && e.name === 'AbortError') {
+				return;
+			}
+			store.$guildsError.set(
+				e instanceof Error
+					? e.message
+					: 'Failed to load Discord guilds',
+			);
+			store.$guildsStale.set(true);
+		} finally {
+			store.$guildsLoading.set(false);
+			if (runtime.guildsAbort === abort) runtime.guildsAbort = null;
+		}
+	}
+
+	async function refreshSelectedGuild(): Promise<void> {
+		const guildId = store.$selectedGuildId.get();
+		if (!guildId) return;
+		const userId = store.$userId.get();
+		if (userId) invalidateCachedTokens(userId, guildId);
+		await api.loadTokens(guildId, true);
+	}
+
+	return { selectGuild, loadOwnedGuilds, refreshSelectedGuild };
+}

package/src/lib/agents/formDrafts.ts

@@ -0,0 +1,55 @@
+import type { BotConfigFormDraft, DiscordshConfig } from './types';
+
+export function emptyBotConfigFormDraft(): BotConfigFormDraft {
+	return {
+		default_repo: '',
+		claim_channel_id: '',
+		forum_channel_id: '',
+		noticeboard_channel_id: '',
+		taskboard_channel_id: '',
+		max_assignees: '2',
+		mirror_pr_events: true,
+		active: true,
+	};
+}
+
+export function botConfigToFormDraft(c: DiscordshConfig): BotConfigFormDraft {
+	const base = emptyBotConfigFormDraft();
+	return {
+		default_repo: c.default_repo ?? base.default_repo,
+		claim_channel_id: c.claim_channel_id ?? base.claim_channel_id,
+		forum_channel_id: c.forum_channel_id ?? base.forum_channel_id,
+		noticeboard_channel_id:
+			c.noticeboard_channel_id ?? base.noticeboard_channel_id,
+		taskboard_channel_id:
+			c.taskboard_channel_id ?? base.taskboard_channel_id,
+		max_assignees:
+			typeof c.max_assignees === 'number'
+				? String(c.max_assignees)
+				: base.max_assignees,
+		mirror_pr_events:
+			typeof c.mirror_pr_events === 'boolean'
+				? c.mirror_pr_events
+				: base.mirror_pr_events,
+		active: typeof c.active === 'boolean' ? c.active : base.active,
+	};
+}
+
+export function botConfigFromFormDraft(f: BotConfigFormDraft): DiscordshConfig {
+	const cfg: DiscordshConfig = {
+		mirror_pr_events: f.mirror_pr_events,
+		active: f.active,
+	};
+	if (f.default_repo.trim()) cfg.default_repo = f.default_repo.trim();
+	if (f.claim_channel_id.trim())
+		cfg.claim_channel_id = f.claim_channel_id.trim();
+	if (f.forum_channel_id.trim())
+		cfg.forum_channel_id = f.forum_channel_id.trim();
+	if (f.noticeboard_channel_id.trim())
+		cfg.noticeboard_channel_id = f.noticeboard_channel_id.trim();
+	if (f.taskboard_channel_id.trim())
+		cfg.taskboard_channel_id = f.taskboard_channel_id.trim();
+	const max = parseInt(f.max_assignees, 10);
+	if (!Number.isNaN(max) && max > 0) cfg.max_assignees = max;
+	return cfg;
+}

package/src/lib/agents/generated/agents-schema.ts

@@ -0,0 +1,155 @@
+/**
+ * AUTO-GENERATED by proto-to-zod — DO NOT EDIT
+ *
+ * Source: ../descriptors/agents.binpb
+ * Config: ../agents-zod-config.json
+ * Generated: 2026-07-20T00:37:21.617Z
+ */
+
+import { z } from 'zod';
+
+export const TokenServices = [
+	'github_webhook',
+	'github',
+	'github_repos',
+	'discordsh_config',
+] as const;
+
+export type TokenServiceValue = (typeof TokenServices)[number];
+
+export const TokenServiceSchema = z.enum(TokenServices);
+
+// PeekTokenResponse
+export const PeekTokenResponseSchema = z.object({
+	value: z.string().optional(),
+});
+
+export type PeekTokenResponse = z.infer<typeof PeekTokenResponseSchema>;
+
+// PeekTokenRequest
+export const PeekTokenRequestSchema = z.object({
+	server_id: z
+		.string()
+		.regex(
+			/^\d{17,20}$/,
+			'Must be a valid Discord snowflake (17-20 digits)',
+		),
+	service: z
+		.string()
+		.regex(
+			/^[a-z0-9_]{2,32}$/,
+			'Service must be 2-32 chars: lowercase a-z, 0-9, underscore',
+		),
+});
+
+export type PeekTokenRequest = z.infer<typeof PeekTokenRequestSchema>;
+
+// ToggleTokenRequest
+export const ToggleTokenRequestSchema = z.object({
+	server_id: z
+		.string()
+		.regex(
+			/^\d{17,20}$/,
+			'Must be a valid Discord snowflake (17-20 digits)',
+		),
+	token_id: z
+		.string()
+		.regex(
+			/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+			'token_id must be a UUID',
+		),
+	is_active: z.boolean(),
+});
+
+export type ToggleTokenRequest = z.infer<typeof ToggleTokenRequestSchema>;
+
+// DeleteTokenRequest
+export const DeleteTokenRequestSchema = z.object({
+	server_id: z
+		.string()
+		.regex(
+			/^\d{17,20}$/,
+			'Must be a valid Discord snowflake (17-20 digits)',
+		),
+	token_id: z
+		.string()
+		.regex(
+			/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+			'token_id must be a UUID',
+		),
+});
+
+export type DeleteTokenRequest = z.infer<typeof DeleteTokenRequestSchema>;
+
+// AgentTokenRow
+export const AgentTokenRowSchema = z.object({
+	token_id: z.string(),
+	token_name: z.string(),
+	service: z.string(),
+	description: z.string().nullish(),
+	is_active: z.boolean(),
+	created_at: z.string(),
+	updated_at: z.string().nullish(),
+});
+
+export type AgentTokenRow = z.infer<typeof AgentTokenRowSchema>;
+
+// ListTokensResponse
+export const ListTokensResponseSchema = z.object({
+	tokens: z.array(AgentTokenRowSchema).optional(),
+});
+
+export type ListTokensResponse = z.infer<typeof ListTokensResponseSchema>;
+
+// ListTokensRequest
+export const ListTokensRequestSchema = z.object({
+	server_id: z
+		.string()
+		.regex(
+			/^\d{17,20}$/,
+			'Must be a valid Discord snowflake (17-20 digits)',
+		),
+});
+
+export type ListTokensRequest = z.infer<typeof ListTokensRequestSchema>;
+
+// SetTokenRequest
+export const SetTokenRequestSchema = z.object({
+	server_id: z
+		.string()
+		.regex(
+			/^\d{17,20}$/,
+			'Must be a valid Discord snowflake (17-20 digits)',
+		),
+	service: z
+		.string()
+		.regex(
+			/^[a-z0-9_]{2,32}$/,
+			'Service must be 2-32 chars: lowercase a-z, 0-9, underscore',
+		),
+	token_name: z
+		.string()
+		.regex(
+			/^[a-z0-9_-]{3,64}$/,
+			'Token name must be 3-64 lowercase chars: a-z, 0-9, underscore, dash',
+		),
+	token_value: z
+		.string()
+		.min(10, 'Token value must be 10-8000 characters')
+		.max(8000, 'Token value must be 10-8000 characters'),
+	description: z.string().optional(),
+});
+
+export type SetTokenRequest = z.infer<typeof SetTokenRequestSchema>;
+
+// AgentError
+export const AgentErrorSchema = z.object({
+	success: z.boolean(),
+	message: z.string(),
+	code: z.number(),
+	sqlstate: z.string().optional(),
+	hint: z.string().optional(),
+	context: z.string().optional(),
+});
+
+export type AgentError = z.infer<typeof AgentErrorSchema>;