@agent-team-foundation/first-tree-hub 0.12.5 → 0.12.6

package/dist/{bootstrap-C_K2CKXC.mjs → bootstrap-BCZC1ki6.mjs}

@@ -576,12 +576,22 @@ const serverConfigSchema = defineConfig({
 		}),
 		githubTokenRepos: field(z.string().optional(), { env: "FIRST_TREE_HUB_CONTEXT_TREE_GITHUB_TOKEN_REPOS" })
 	}),
-	oauth: optional({ github: optional({
-		clientId: field(z.string(), { env: "FIRST_TREE_HUB_GITHUB_OAUTH_CLIENT_ID" }),
-		clientSecret: field(z.string(), {
-			env: "FIRST_TREE_HUB_GITHUB_OAUTH_CLIENT_SECRET",
+	oauth: optional({ githubApp: optional({
+		appId: field(z.string().min(1), { env: "FIRST_TREE_HUB_GITHUB_APP_ID" }),
+		clientId: field(z.string().min(1), { env: "FIRST_TREE_HUB_GITHUB_APP_CLIENT_ID" }),
+		clientSecret: field(z.string().min(1), {
+			env: "FIRST_TREE_HUB_GITHUB_APP_CLIENT_SECRET",
 			secret: true
-		})
+		}),
+		privateKeyPem: field(z.string().min(1), {
+			env: "FIRST_TREE_HUB_GITHUB_APP_PRIVATE_KEY",
+			secret: true
+		}),
+		webhookSecret: field(z.string().min(1), {
+			env: "FIRST_TREE_HUB_GITHUB_APP_WEBHOOK_SECRET",
+			secret: true
+		}),
+		slug: field(z.string().min(1).optional(), { env: "FIRST_TREE_HUB_GITHUB_APP_SLUG" })
 	}) }),
 	cors: optional({ origin: field(z.string(), { env: "FIRST_TREE_HUB_CORS_ORIGIN" }) }),
 	trustProxy: field(z.boolean().default(false), { env: "FIRST_TREE_HUB_TRUST_PROXY" }),

package/dist/cli/index.mjs

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 import "../observability-BAScT_5S-BcW9HgkG.mjs";
-import { $ as formatStaleReason, A as checkDocker, B as isServiceSupported, C as createApiNameResolver, D as checkBackgroundService, E as checkAgentConfigs, F as checkWebSocket, H as restartClientService, I as printResults, J as stopPostgres, L as reconcileAgentConfigs, M as checkServerConfig, N as checkServerHealth, O as checkClientConfig, P as checkServerReachable, Q as findStaleAliases, R as getClientServiceStatus, S as runHomeMigration, T as runMigrations, U as startClientService, W as stopClientService, X as handleClientOrgMismatch, Y as ClientRuntime, _ as formatCheckReport, a as declineUpdate, at as fail, b as onboardCreate, c as detectInstallMode, ct as ClientUserMismatchError, d as startServer, dt as SessionRegistry, et as removeLocalAgent, f as reconcileLocalRuntimeProviders, ft as cleanWorkspaces, g as promptMissingFields, h as promptAddAgent, ht as configureClientLoggerForService, i as createExecuteUpdate, it as resolveSenderName, j as checkNodeVersion, k as checkDatabase, l as fetchLatestVersion, lt as FirstTreeHubSDK, m as isInteractive, mt as applyClientLoggerConfig, o as promptUpdate, ot as success, p as uploadClientCapabilities, pt as probeCapabilities, r as registerSaaSConnectCommand, rt as resolveReplyToFromEnv, s as PACKAGE_NAME, st as ClientOrgMismatchError, tt as createOwner, u as installGlobalLatest, ut as SdkError, v as loadOnboardState, w as migrateLocalAgentDirs, x as saveOnboardState, y as onboardCheck, z as installClientService } from "../saas-connect-DYjvx5yr.mjs";
+import { $ as formatStaleReason, A as checkDocker, B as isServiceSupported, C as createApiNameResolver, D as checkBackgroundService, E as checkAgentConfigs, F as checkWebSocket, H as restartClientService, I as printResults, J as stopPostgres, L as reconcileAgentConfigs, M as checkServerConfig, N as checkServerHealth, O as checkClientConfig, P as checkServerReachable, Q as findStaleAliases, R as getClientServiceStatus, S as runHomeMigration, T as runMigrations, U as startClientService, W as stopClientService, X as handleClientOrgMismatch, Y as ClientRuntime, _ as formatCheckReport, a as declineUpdate, at as fail, b as onboardCreate, c as detectInstallMode, ct as ClientUserMismatchError, d as startServer, dt as SessionRegistry, et as removeLocalAgent, f as reconcileLocalRuntimeProviders, ft as cleanWorkspaces, g as promptMissingFields, h as promptAddAgent, ht as configureClientLoggerForService, i as createExecuteUpdate, it as resolveSenderName, j as checkNodeVersion, k as checkDatabase, l as fetchLatestVersion, lt as FirstTreeHubSDK, m as isInteractive, mt as applyClientLoggerConfig, o as promptUpdate, ot as success, p as uploadClientCapabilities, pt as probeCapabilities, r as registerSaaSConnectCommand, rt as resolveReplyToFromEnv, s as PACKAGE_NAME, st as ClientOrgMismatchError, tt as createOwner, u as installGlobalLatest, ut as SdkError, v as loadOnboardState, w as migrateLocalAgentDirs, x as saveOnboardState, y as onboardCheck, z as installClientService } from "../saas-connect-RCN8zL5e.mjs";
 import "../logger-core-BTmvdflj-DjW8FM4T.mjs";
-import { C as resetConfigMeta, E as setConfigValue, S as resetConfig, T as serverConfigSchema, _ as getConfigValue, a as ensureFreshAdminToken, c as resolveServerUrl, d as DEFAULT_CONFIG_DIR, f as DEFAULT_DATA_DIR, h as clientConfigSchema, i as ensureFreshAccessToken, l as saveAgentConfig, m as agentConfigSchema, o as loadCredentials, p as DEFAULT_HOME_DIR, u as saveCredentials, v as initConfig, w as resolveConfigReadonly, x as readConfigFile, y as loadAgents } from "../bootstrap-C_K2CKXC.mjs";
+import { C as resetConfigMeta, E as setConfigValue, S as resetConfig, T as serverConfigSchema, _ as getConfigValue, a as ensureFreshAdminToken, c as resolveServerUrl, d as DEFAULT_CONFIG_DIR, f as DEFAULT_DATA_DIR, h as clientConfigSchema, i as ensureFreshAccessToken, l as saveAgentConfig, m as agentConfigSchema, o as loadCredentials, p as DEFAULT_HOME_DIR, u as saveCredentials, v as initConfig, w as resolveConfigReadonly, x as readConfigFile, y as loadAgents } from "../bootstrap-BCZC1ki6.mjs";
 import { a as print, n as CLI_USER_AGENT, o as setJsonMode, r as COMMAND_VERSION, t as cliFetch } from "../cli-fetch--tiwKm5S.mjs";
-import "../dist-BwPlBZWi.mjs";
-import { n as bindFeishuUser, t as bindFeishuBot } from "../feishu-CKGzIamp.mjs";
+import "../dist-xP6NpdMp.mjs";
+import { n as bindFeishuUser, t as bindFeishuBot } from "../feishu-CsfadBKa.mjs";
 import "../errors-CF5evtJt-B0NTIVPt.mjs";
 import "../src-DNBS5Yjj.mjs";
-import "../client-DL5vHhvQ-CnYGq2x-.mjs";
+import "../client-B89AKi3Q-DAyGdQSq.mjs";
 import "../invitation-Bg0TRiyx-BsZH4GCS.mjs";
 import { join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
@@ -1672,13 +1672,13 @@ function isSecretField(schema, dotPath) {
 //#region src/commands/onboard.ts
 async function promptMissing(args) {
 	if (!args.server) try {
-		const { resolveServerUrl } = await import("../bootstrap-C_K2CKXC.mjs").then((n) => n.r);
+		const { resolveServerUrl } = await import("../bootstrap-BCZC1ki6.mjs").then((n) => n.r);
 		resolveServerUrl();
 	} catch {
 		args.server = await input({ message: "Hub server URL:" });
 		saveOnboardState(args);
 	}
-	const { loadCredentials } = await import("../bootstrap-C_K2CKXC.mjs").then((n) => n.r);
+	const { loadCredentials } = await import("../bootstrap-BCZC1ki6.mjs").then((n) => n.r);
 	if (!loadCredentials()) throw new Error("No saved credentials. Run `first-tree-hub client connect <server-url>` before onboarding.");
 	if (!args.id) {
 		args.id = await input({ message: "Agent ID:" });

package/dist/{client-DL5vHhvQ-CnYGq2x-.mjs → client-B89AKi3Q-DAyGdQSq.mjs}

@@ -1,10 +1,10 @@
 import { O as withSpan, f as messageAttrs, s as createLogger } from "./observability-BAScT_5S-BcW9HgkG.mjs";
-import { X as questionAnswerMessageContentSchema, Z as questionMessageContentSchema, _ as clientCapabilitiesSchema, a as AGENT_VISIBILITY, i as AGENT_STATUSES, j as extractMentions, nt as scanMentionTokens } from "./dist-BwPlBZWi.mjs";
+import { $ as questionMessageContentSchema, M as extractMentions, O as defaultParticipantMode, Q as questionAnswerMessageContentSchema, _ as clientCapabilitiesSchema, a as AGENT_VISIBILITY, h as agentTypeSchema, i as AGENT_STATUSES, it as scanMentionTokens } from "./dist-xP6NpdMp.mjs";
 import { a as ConflictError, i as ClientUserMismatchError, l as organizations, n as BadRequestError, o as ForbiddenError, s as NotFoundError, u as users } from "./errors-CF5evtJt-B0NTIVPt.mjs";
 import { randomUUID } from "node:crypto";
 import { and, desc, eq, inArray, isNotNull, lt, ne, or, sql } from "drizzle-orm";
 import { bigserial, boolean, index, integer, jsonb, pgTable, primaryKey, text, timestamp, unique } from "drizzle-orm/pg-core";
-//#region ../server/dist/client-DL5vHhvQ.mjs
+//#region ../server/dist/client-B89AKi3Q.mjs
 /**
 * Client connections. A client is a single SDK process (AgentRuntime) that may
 * host multiple agents. From the unified-user-token milestone on, a client is
@@ -185,6 +185,140 @@ function invalidateChatAudience(chatId) {
 	cache.delete(chatId);
 }
 /**
+* Single source of truth for writing `chat_participants`.
+*
+* **This is the ONLY place in the codebase that may `INSERT` into the
+* `chat_participants` table.** Do not call `tx.insert(chatParticipants)`
+* or `db.insert(chatParticipants)` from anywhere else. The original bug
+* (docs/chat-participant-mode-fix-design.md §1.1) was caused by ten
+* scattered insert sites each re-deriving the `mode` rule, several of
+* which violated `group + non-human ⇒ mention_only`. Re-introducing a
+* second writer reopens that hole — please don't.
+*
+* Test fixtures under `src/__tests__/` that deliberately seed
+* pathological rows (e.g. cross-org pollution tests) may bypass this
+* rule; they are setting up "what bad data looks like" rather than
+* exercising the production write path.
+*
+* All callers that need to add a participant — `createChat`, `addParticipant`,
+* `ensureParticipant`, `joinChat`, `createMeChat`, `addMeChatParticipants`,
+* `findOrCreateDirectChat`, `findOrCreateChatForChannel`, `joinAsParticipant`,
+* … — go through `addChatParticipants`. The function performs ONE round-trip
+* to read `chats.type` + every involved `agents.type`, runs each row through
+* `defaultParticipantMode`, and inserts the result. `agents.type` is parsed
+* through the shared `agentTypeSchema` so schema drift surfaces loudly
+* instead of silently coercing to a default.
+*
+* `changeChatType` complements it on the type-flip path: when a `direct`
+* chat is being upgraded to `group` by the very next participant insert, the
+* existing non-human rows must be re-graded to `mention_only`. Callers that
+* trigger an upgrade are expected to invoke `changeChatType` BEFORE
+* `addChatParticipants`, inside the same transaction, so the new row picks
+* up the post-upgrade `chats.type` and existing rows get re-graded together.
+*/
+/**
+* Insert participant rows whose `mode` is derived from `(chats.type, agents.type)`.
+*
+* Reads:
+*   - `chats.type` for the target chat (NotFoundError on missing)
+*   - `agents.type` for every requested participant (BadRequestError on missing)
+*
+* Mode derivation:
+*   - for each row, `peerAgentTypes` is the type of every OTHER participant
+*     being inserted in the same call PLUS every EXISTING participant of
+*     the chat. This matters only for `direct` chats; the helper ignores
+*     it for `group` / `thread`.
+*
+* Writes one INSERT (multi-row) per call.
+*
+* No watcher / audience-cache side effects — the caller owns those, since
+* different entrypoints have different surrounding work (state-carry, watcher
+* recompute, audience invalidation). Keeping this module side-effect-free
+* makes it testable from any tx context.
+*/
+async function addChatParticipants(tx, chatId, participants, options = {}) {
+	if (participants.length === 0) return;
+	const [chat] = await tx.select({ type: chats.type }).from(chats).where(eq(chats.id, chatId)).limit(1);
+	if (!chat) throw new NotFoundError(`Chat "${chatId}" not found`);
+	if (chat.type !== "direct" && chat.type !== "group" && chat.type !== "thread") throw new Error(`Unexpected chat type "${chat.type}" for chat "${chatId}"`);
+	const chatType = chat.type;
+	const agentIds = participants.map((p) => p.agentId);
+	const agentRows = await tx.select({
+		uuid: agents.uuid,
+		type: agents.type
+	}).from(agents).where(inArray(agents.uuid, agentIds));
+	const agentTypeById = /* @__PURE__ */ new Map();
+	for (const row of agentRows) agentTypeById.set(row.uuid, row.type);
+	const missing = agentIds.filter((id) => !agentTypeById.has(id));
+	if (missing.length > 0) throw new BadRequestError(`Agents not found: ${missing.join(", ")}`);
+	if (options.assertHuman) {
+		const nonHuman = agentRows.filter((a) => a.type !== "human");
+		if (nonHuman.length > 0) throw new BadRequestError(`assertHuman violated: agents must be of type 'human' but got ${nonHuman.map((a) => `${a.uuid}=${a.type}`).join(", ")}`);
+	}
+	let existingAgentTypes = [];
+	if (chatType === "direct") existingAgentTypes = await loadExistingAgentTypes(tx, chatId, new Set(agentIds));
+	const rows = participants.map((spec) => {
+		const rawAgentType = agentTypeById.get(spec.agentId);
+		if (rawAgentType === void 0) throw new Error("Unexpected: agent type lookup unset after presence check");
+		const agentType = agentTypeSchema.parse(rawAgentType);
+		const peerTypesForRow = chatType === "direct" ? [...existingAgentTypes, ...participants.filter((p) => p.agentId !== spec.agentId).map((p) => agentTypeById.get(p.agentId)).filter((t) => t !== void 0)].map((t) => agentTypeSchema.parse(t)) : [];
+		return {
+			chatId,
+			agentId: spec.agentId,
+			role: spec.role ?? "member",
+			mode: defaultParticipantMode(chatType, agentType, peerTypesForRow),
+			lastReadAt: spec.carriedReadState?.lastReadAt ?? null,
+			unreadMentionCount: spec.carriedReadState?.unreadMentionCount ?? 0
+		};
+	});
+	const insert = tx.insert(chatParticipants).values(rows);
+	if (options.onConflictDoNothing) await insert.onConflictDoNothing({ target: [chatParticipants.chatId, chatParticipants.agentId] });
+	else await insert;
+}
+async function loadExistingAgentTypes(tx, chatId, excludeAgentIds) {
+	return (await tx.select({
+		type: agents.type,
+		agentId: chatParticipants.agentId
+	}).from(chatParticipants).innerJoin(agents, eq(chatParticipants.agentId, agents.uuid)).where(eq(chatParticipants.chatId, chatId))).filter((r) => !excludeAgentIds.has(r.agentId)).map((r) => r.type);
+}
+/**
+* Upgrade `chats.type` from `direct` → `group` AND re-grade every existing
+* non-human participant to `mention_only`. Idempotent: if `chat.type` is
+* already `group` (or any non-`direct` value), no-op.
+*
+* Callers that are about to insert a 3rd participant on a `direct` chat
+* invoke this BEFORE `addChatParticipants` so the new row picks up the
+* post-upgrade `chats.type` and the existing rows are re-graded in the
+* same transaction.
+*
+* Note: this is the replacement for `services/chat.ts`'s
+* `maybeUpgradeDirectToGroup` (the one in `services/watcher.ts` is
+* removed). Keep the rename: `changeChatType` is more precise about the
+* primary mutation; `maybe…ToGroup` overstated the conditional gate.
+*/
+async function changeChatType(tx, chatId, newType) {
+	const [chat] = await tx.select({ type: chats.type }).from(chats).where(eq(chats.id, chatId)).limit(1);
+	if (!chat) throw new NotFoundError(`Chat "${chatId}" not found`);
+	if (chat.type === newType) return;
+	if (newType === "group" && chat.type !== "direct") throw new BadRequestError(`Cannot change chat type from "${chat.type}" to "${newType}"`);
+	await tx.update(chats).set({
+		type: newType,
+		updatedAt: /* @__PURE__ */ new Date()
+	}).where(eq(chats.id, chatId));
+	const ids = (await tx.select({ agentId: chatParticipants.agentId }).from(chatParticipants).innerJoin(agents, eq(chatParticipants.agentId, agents.uuid)).where(and(eq(chatParticipants.chatId, chatId), ne(agents.type, "human")))).map((r) => r.agentId);
+	if (ids.length === 0) return;
+	await tx.update(chatParticipants).set({ mode: "mention_only" }).where(and(eq(chatParticipants.chatId, chatId), inArray(chatParticipants.agentId, ids)));
+}
+/**
+* Heuristic for whether an insert about to happen would push the chat past
+* the direct → group threshold. Pure helper so callers can decide whether
+* to call `changeChatType` before `addChatParticipants` without re-deriving
+* the rule locally.
+*/
+function wouldUpgradeToGroup(currentParticipantCount, newParticipantCount) {
+	return currentParticipantCount + newParticipantCount >= 3;
+}
+/**
 * Chat-first workspace — watcher subscription helpers.
 *
 * Watchers (rows in `chat_subscriptions`) are non-speaking observers. A
@@ -276,24 +410,6 @@ async function recomputeWatchersForMember(db, memberId) {
 	for (const { chatId } of rows) await recomputeChatWatchers(db, chatId);
 }
 /**
-* Mirror of `services/chat.ts` `maybeUpgradeDirectToGroup`. Inlined here so
-* `joinAsParticipant` keeps the upgrade rule + the state carry in one
-* transaction without depending on chat.ts (avoids a circular import).
-*/
-async function maybeUpgradeDirectToGroup$1(tx, chatId, existingParticipantIds) {
-	if (existingParticipantIds.length + 1 < 3) return;
-	const [chat] = await tx.select({ type: chats.type }).from(chats).where(eq(chats.id, chatId)).limit(1);
-	if (!chat || chat.type !== "direct") return;
-	await tx.update(chats).set({
-		type: "group",
-		updatedAt: /* @__PURE__ */ new Date()
-	}).where(eq(chats.id, chatId));
-	if (existingParticipantIds.length === 0) return;
-	const ids = (await tx.select({ uuid: agents.uuid }).from(agents).where(and(inArray(agents.uuid, existingParticipantIds), ne(agents.type, "human")))).map((r) => r.uuid);
-	if (ids.length === 0) return;
-	await tx.update(chatParticipants).set({ mode: "mention_only" }).where(and(eq(chatParticipants.chatId, chatId), inArray(chatParticipants.agentId, ids)));
-}
-/**
 * Watcher → speaking participant. State-carry transaction.
 *
 *   1. DELETE the watcher row (returning read state).
@@ -318,15 +434,15 @@ async function joinAsParticipant(db, chatId, humanAgentId) {
 			inserted: false,
 			carried: carriedRow ?? null
 		};
-		await maybeUpgradeDirectToGroup$1(tx, chatId, (await tx.select({ agentId: chatParticipants.agentId }).from(chatParticipants).where(eq(chatParticipants.chatId, chatId))).map((p) => p.agentId));
-		await tx.insert(chatParticipants).values({
-			chatId,
+		if (wouldUpgradeToGroup((await tx.select({ agentId: chatParticipants.agentId }).from(chatParticipants).where(eq(chatParticipants.chatId, chatId))).length, 1)) await changeChatType(tx, chatId, "group");
+		await addChatParticipants(tx, chatId, [{
 			agentId: humanAgentId,
 			role: "member",
-			mode: "full",
-			lastReadAt: carriedRow?.lastReadAt ?? null,
-			unreadMentionCount: carriedRow?.unreadMentionCount ?? 0
-		});
+			carriedReadState: carriedRow ? {
+				lastReadAt: carriedRow.lastReadAt,
+				unreadMentionCount: carriedRow.unreadMentionCount
+			} : void 0
+		}], { assertHuman: true });
 		return {
 			chatId,
 			inserted: true,
@@ -405,28 +521,6 @@ function ensureCanJoin(membership) {
 	if (membership === "participant") throw new ConflictError("Already a participant in this chat");
 	if (membership === null) throw new ForbiddenError("Not a watcher of this chat — open the chat from your workspace before joining");
 }
-/**
-* When a direct chat grows past 2 participants, upgrade it to `group` and
-* flip every existing non-human agent participant to `mention_only` — see
-* proposals/hub-agent-messaging-reply-and-mentions §3.3. The caller is
-* expected to insert the new participant AFTER this runs, so the "existing"
-* set excludes them.
-*
-* Idempotent: if the chat is already a group, no-op.
-*/
-async function maybeUpgradeDirectToGroup(db, chatId, existingParticipantIds, newParticipantCount) {
-	if (existingParticipantIds.length + newParticipantCount < 3) return;
-	const [chat] = await db.select({ type: chats.type }).from(chats).where(eq(chats.id, chatId)).limit(1);
-	if (!chat || chat.type !== "direct") return;
-	await db.update(chats).set({
-		type: "group",
-		updatedAt: /* @__PURE__ */ new Date()
-	}).where(eq(chats.id, chatId));
-	if (existingParticipantIds.length === 0) return;
-	const ids = (await db.select({ uuid: agents.uuid }).from(agents).where(and(inArray(agents.uuid, existingParticipantIds), ne(agents.type, "human")))).map((a) => a.uuid);
-	if (ids.length === 0) return;
-	await db.update(chatParticipants).set({ mode: "mention_only" }).where(and(eq(chatParticipants.chatId, chatId), inArray(chatParticipants.agentId, ids)));
-}
 async function createChat(db, creatorId, data) {
 	const chatId = randomUUID();
 	const allParticipantIds = new Set([creatorId, ...data.participantIds]);
@@ -444,7 +538,6 @@ async function createChat(db, creatorId, data) {
 	const orgId = creator.organizationId;
 	const crossOrg = existingAgents.filter((a) => a.organizationId !== orgId);
 	if (crossOrg.length > 0) throw new BadRequestError(`Cross-organization chat not allowed: ${crossOrg.map((a) => a.id).join(", ")}`);
-	const isDirectAgentOnly = data.type === "direct" && existingAgents.every((a) => a.type !== "human");
 	return db.transaction(async (tx) => {
 		const [chat] = await tx.insert(chats).values({
 			id: chatId,
@@ -453,13 +546,10 @@ async function createChat(db, creatorId, data) {
 			topic: data.topic ?? null,
 			metadata: data.metadata ?? {}
 		}).returning();
-		const participantRows = [...allParticipantIds].map((agentId) => ({
-			chatId,
+		await addChatParticipants(tx, chatId, [...allParticipantIds].map((agentId) => ({
 			agentId,
-			role: agentId === creatorId ? "owner" : "member",
-			...isDirectAgentOnly ? { mode: "mention_only" } : {}
-		}));
-		await tx.insert(chatParticipants).values(participantRows);
+			role: agentId === creatorId ? "owner" : "member"
+		})));
 		await recomputeChatWatchers(tx, chatId);
 		const participants = await tx.select().from(chatParticipants).where(eq(chatParticipants.chatId, chatId));
 		if (!chat) throw new Error("Unexpected: INSERT RETURNING produced no row");
@@ -532,13 +622,9 @@ async function ensureParticipant(db, chatId, agentId) {
 	const [existing] = await db.select({ agentId: chatParticipants.agentId }).from(chatParticipants).where(and(eq(chatParticipants.chatId, chatId), eq(chatParticipants.agentId, agentId))).limit(1);
 	if (existing) return;
 	await db.transaction(async (tx) => {
-		await maybeUpgradeDirectToGroup(tx, chatId, (await tx.select({ agentId: chatParticipants.agentId }).from(chatParticipants).where(eq(chatParticipants.chatId, chatId))).map((p) => p.agentId), 1);
+		if (wouldUpgradeToGroup((await tx.select({ agentId: chatParticipants.agentId }).from(chatParticipants).where(eq(chatParticipants.chatId, chatId))).length, 1)) await changeChatType(tx, chatId, "group");
 		await tx.delete(chatSubscriptions).where(and(eq(chatSubscriptions.chatId, chatId), eq(chatSubscriptions.agentId, agentId)));
-		await tx.insert(chatParticipants).values({
-			chatId,
-			agentId,
-			mode: "full"
-		}).onConflictDoNothing({ target: [chatParticipants.chatId, chatParticipants.agentId] });
+		await addChatParticipants(tx, chatId, [{ agentId }], { onConflictDoNothing: true });
 		await recomputeChatWatchers(tx, chatId);
 	});
 	invalidateChatAudience(chatId);
@@ -555,13 +641,9 @@ async function addParticipant(db, chatId, requesterId, data) {
 	const [existing] = await db.select({ chatId: chatParticipants.chatId }).from(chatParticipants).where(and(eq(chatParticipants.chatId, chatId), eq(chatParticipants.agentId, data.agentId))).limit(1);
 	if (existing) throw new ConflictError(`Agent "${data.agentId}" is already a participant`);
 	await db.transaction(async (tx) => {
-		await maybeUpgradeDirectToGroup(tx, chatId, (await tx.select({ agentId: chatParticipants.agentId }).from(chatParticipants).where(eq(chatParticipants.chatId, chatId))).map((p) => p.agentId), 1);
+		if (wouldUpgradeToGroup((await tx.select({ agentId: chatParticipants.agentId }).from(chatParticipants).where(eq(chatParticipants.chatId, chatId))).length, 1)) await changeChatType(tx, chatId, "group");
 		await tx.delete(chatSubscriptions).where(and(eq(chatSubscriptions.chatId, chatId), eq(chatSubscriptions.agentId, data.agentId)));
-		await tx.insert(chatParticipants).values({
-			chatId,
-			agentId: data.agentId,
-			mode: data.mode ?? "full"
-		});
+		await addChatParticipants(tx, chatId, [{ agentId: data.agentId }]);
 		await recomputeChatWatchers(tx, chatId);
 	});
 	invalidateChatAudience(chatId);
@@ -669,15 +751,15 @@ async function joinChat(db, chatId, memberId, humanAgentId) {
 			lastReadAt: chatSubscriptions.lastReadAt,
 			unreadMentionCount: chatSubscriptions.unreadMentionCount
 		});
-		await maybeUpgradeDirectToGroup(tx, chatId, participantAgentIds, 1);
-		await tx.insert(chatParticipants).values({
-			chatId,
+		if (wouldUpgradeToGroup(participantAgentIds.length, 1)) await changeChatType(tx, chatId, "group");
+		await addChatParticipants(tx, chatId, [{
 			agentId: humanAgentId,
 			role: "member",
-			mode: "full",
-			lastReadAt: carriedRow?.lastReadAt ?? null,
-			unreadMentionCount: carriedRow?.unreadMentionCount ?? 0
-		});
+			carriedReadState: carriedRow ? {
+				lastReadAt: carriedRow.lastReadAt,
+				unreadMentionCount: carriedRow.unreadMentionCount
+			} : void 0
+		}], { assertHuman: true });
 		await recomputeChatWatchers(tx, chatId);
 	});
 	invalidateChatAudience(chatId);
@@ -719,7 +801,6 @@ async function findOrCreateDirectChat(db, agentAId, agentBId) {
 		const directChats = await db.select().from(chats).where(and(inArray(chats.id, commonChatIds), eq(chats.type, "direct"), eq(chats.organizationId, orgId))).orderBy(chats.createdAt, chats.id).limit(1);
 		if (directChats.length > 0 && directChats[0]) return directChats[0];
 	}
-	const mode = agentA.type !== "human" && agentB.type !== "human" ? "mention_only" : "full";
 	const chatId = randomUUID();
 	return db.transaction(async (tx) => {
 		const [chat] = await tx.insert(chats).values({
@@ -727,16 +808,12 @@ async function findOrCreateDirectChat(db, agentAId, agentBId) {
 			organizationId: orgId,
 			type: "direct"
 		}).returning();
-		await tx.insert(chatParticipants).values([{
-			chatId,
+		await addChatParticipants(tx, chatId, [{
 			agentId: agentAId,
-			role: "member",
-			mode
+			role: "member"
 		}, {
-			chatId,
 			agentId: agentBId,
-			role: "member",
-			mode
+			role: "member"
 		}]);
 		await recomputeChatWatchers(tx, chatId);
 		if (!chat) throw new Error("Unexpected: INSERT RETURNING produced no row");
@@ -2051,4 +2128,4 @@ async function cleanupStaleClients(db, staleSeconds = 60) {
 	return result.length;
 }
 //#endregion
-export { pendingQuestions as $, heartbeatClient as A, listAgentsWithRuntime as B, findOrCreateDirectChat as C, getClient as D, getChatDetail as E, joinChat as F, listClientsForOrgAdmin as G, listChats as H, leaveAsParticipant as I, markStaleAgents as J, listMessages as K, leaveChat as L, inboxEntries as M, invalidateChatAudience as N, getOnlineCount as O, joinAsParticipant as P, notifyRecipients as Q, listActiveAgentsPinnedToClient as R, ensureParticipant as S, getCachedAudience as T, listChatsForMember as U, listChatParticipantsWithNames as V, listClients as W, members as X, markSupersededByChat as Y, messages as Z, createNotifier as _, updateClientCapabilities as _t, agents as a, removeParticipant as at, editMessage as b, bindAgent as c, retireClient as ct, chats as d, serverInstances as dt, recomputeChatWatchers as et, claimClient as f, setOffline as ft, createChat as g, unbindAgent as gt, clients as h, touchAgent as ht, agentVisibilityCondition as i, registerClient as it, heartbeatInstance as j, getPresence as k, chatParticipants as l, sendMessage as lt, cleanupStalePresence as m, submitAnswer as mt, agentChatSessions as n, recomputeWatchersForMember as nt, assertClientOwner as o, resetActivity as ot, cleanupStaleClients as p, setRuntimeState as pt, listMyPinnedAgents as q, agentPresence as r, registerChatMessageDispatcher as rt, assertParticipant as s, resolveChatMembership as st, addParticipant as t, recomputeWatchersForAgent as tt, chatSubscriptions as u, sendToAgent as ut, deriveAuthState as v, upsertSessionState as vt, getActivityOverview as w, ensureCanJoin as x, disconnectClient as y, listAgentsManagedByUser as z };
+export { messages as $, getOnlineCount as A, listActiveAgentsPinnedToClient as B, ensureCanJoin as C, getCachedAudience as D, getActivityOverview as E, invalidateChatAudience as F, listChatsForMember as G, listAgentsWithRuntime as H, joinAsParticipant as I, listMessages as J, listClients as K, joinChat as L, heartbeatClient as M, heartbeatInstance as N, getChatDetail as O, inboxEntries as P, members as Q, leaveAsParticipant as R, editMessage as S, findOrCreateDirectChat as T, listChatParticipantsWithNames as U, listAgentsManagedByUser as V, listChats as W, markStaleAgents as X, listMyPinnedAgents as Y, markSupersededByChat as Z, clients as _, touchAgent as _t, agentVisibilityCondition as a, registerChatMessageDispatcher as at, deriveAuthState as b, upsertSessionState as bt, assertParticipant as c, resetActivity as ct, chatParticipants as d, sendMessage as dt, notifyRecipients as et, chatSubscriptions as f, sendToAgent as ft, cleanupStalePresence as g, submitAnswer as gt, cleanupStaleClients as h, setRuntimeState as ht, agentPresence as i, recomputeWatchersForMember as it, getPresence as j, getClient as k, bindAgent as l, resolveChatMembership as lt, claimClient as m, setOffline as mt, addParticipant as n, recomputeChatWatchers as nt, agents as o, registerClient as ot, chats as p, serverInstances as pt, listClientsForOrgAdmin as q, agentChatSessions as r, recomputeWatchersForAgent as rt, assertClientOwner as s, removeParticipant as st, addChatParticipants as t, pendingQuestions as tt, changeChatType as u, retireClient as ut, createChat as v, unbindAgent as vt, ensureParticipant as w, disconnectClient as x, createNotifier as y, updateClientCapabilities as yt, leaveChat as z };

package/dist/{client-DSM_opoz-BH5eegXb.mjs → client-GOgUQxVe-Dqk9oZf9.mjs}

@@ -1,7 +1,7 @@
 import "./observability-BAScT_5S-BcW9HgkG.mjs";
 import "./logger-core-BTmvdflj-DjW8FM4T.mjs";
-import "./dist-BwPlBZWi.mjs";
+import "./dist-xP6NpdMp.mjs";
 import "./errors-CF5evtJt-B0NTIVPt.mjs";
 import "./src-DNBS5Yjj.mjs";
-import { q as listMyPinnedAgents } from "./client-DL5vHhvQ-CnYGq2x-.mjs";
+import { Y as listMyPinnedAgents } from "./client-B89AKi3Q-DAyGdQSq.mjs";
 export { listMyPinnedAgents };

package/dist/{dist-BwPlBZWi.mjs → dist-xP6NpdMp.mjs}

@@ -45,6 +45,39 @@ function scanMentionTokens(content) {
 	return tokens;
 }
 /**
+* Derive the `chat_participants.mode` that a freshly inserted row MUST get,
+* given the chat's `type` and the joining agent's `type`. This is the single
+* authoritative rule for the invariant
+*
+*   `(chat.type === 'group' && agent.type !== 'human') ⇒ mode === 'mention_only'`
+*
+* plus the legacy "agent-only direct chat" anti-echo rule. The helper is
+* pure and synchronous; all DB lookups are the caller's responsibility (see
+* `services/participant-mode.ts::addChatParticipants` for the canonical
+* server entrypoint that wires it).
+*
+* Rule (encoded once, here):
+*
+*   - `agent.type === 'human'`                          → 'full'
+*   - `chat.type  === 'group'` (and agent is non-human) → 'mention_only'
+*   - `chat.type  === 'direct'` + agent non-human:
+*       - if every other participant on this chat is also non-human →
+*         'mention_only' (prevents the A↔B reply loop noted in migration
+*         0029)
+*       - otherwise → 'full' (the peer is a human / external user, so the
+*         agent should listen to every message in this 1:1 line)
+*
+* `peerAgentTypes` is read only in the `direct` branch; callers may pass
+* an empty array (or omit it) for `group` chats — it's ignored. Watcher /
+* subscription-side `chat_subscriptions` rows are unaffected; the helper
+* only governs the "speaking" mode column.
+*/
+function defaultParticipantMode(chatType, agentType, peerAgentTypes = []) {
+	if (agentType === "human") return "full";
+	if (chatType === "group" || chatType === "thread") return "mention_only";
+	return peerAgentTypes.every((t) => t !== "human") ? "mention_only" : "full";
+}
+/**
 * Single source of truth for "is this string safe to redirect to after a
 * successful OAuth callback".
 *
@@ -626,10 +659,17 @@ z.object({
 	firstMessagePreview: z.string().nullable()
 });
 const updateChatSchema = z.object({ topic: z.string().trim().max(500).nullable() });
-const addParticipantSchema = z.object({
-	agentId: z.string().min(1),
-	mode: z.enum(["full", "mention_only"]).default("full")
-});
+/**
+* Public API body for `POST /api/v1/agent/chats/:chatId/participants`.
+* Phase 1 removed the `mode` field: participant mode is derived server-side
+* from `(chats.type, agents.type)` via `services/participant-mode.ts` and
+* cannot be overridden by the caller. The handler still inspects the raw
+* body and rejects with `400 MODE_FIELD_DEPRECATED` if `mode` is present,
+* so an out-of-tree caller that still sends it gets a clear error and a
+* telemetry counter increments — see `chat-participant-mode-fix-design.md`
+* §3.2 / §6.
+*/
+const addParticipantSchema = z.object({ agentId: z.string().min(1) });
 z.object({ agentId: z.string().min(1) });
 const clientStatusSchema = z.enum(["connected", "disconnected"]);
 /**
@@ -813,6 +853,62 @@ const contextTreeSnapshotSchema = z.object({
 	edges: z.array(contextTreeEdgeSchema),
 	changes: z.array(contextTreeChangeSchema)
 });
+const githubAccountTypeSchema = z.enum(["User", "Organization"]);
+const githubPermissionLevelSchema = z.enum([
+	"read",
+	"write",
+	"admin"
+]);
+/**
+* `installation.permissions` blob from GitHub. Key is the permission name
+* (`contents`, `pull_requests`, `issues`, `members`, …) — we keep this as a
+* free-form `z.record` because GitHub adds new permission keys over time
+* and we don't want a Hub-side `app_id` upgrade just to surface a new key
+* in the integrations panel.
+*/
+const githubAppInstallationPermissionsSchema = z.record(z.string(), githubPermissionLevelSchema);
+/**
+* Subscribed event-name list, e.g. `["issues", "pull_request", "push"]`.
+* Free-form for the same forward-compat reason as `permissions`.
+*/
+const githubAppInstallationEventsSchema = z.array(z.string());
+z.object({
+	login: z.string().optional(),
+	accessToken: z.string().optional(),
+	accessTokenExpiresAt: z.string().datetime({ offset: true }).optional(),
+	refreshToken: z.string().optional(),
+	refreshTokenExpiresAt: z.string().datetime({ offset: true }).optional()
+});
+/**
+* GET-side projection returned by the Hub admin API for the Integrations
+* panel. Secrets are never echoed — only the metadata needed to render
+* "you're connected as @octocat (Organization), 7 repos selected".
+*
+* `selectedRepoCount` is derived from a separate join (App webhook
+* `installation_repositories` events update a children table not modeled
+* here yet); included now so the panel's API shape is stable from the
+* first ship.
+*/
+/**
+* Body for `POST /orgs/:orgId/github-app-installation/claim` — manual
+* recovery for an installation row that ended up unbound (codex P1-5 + H1).
+* The orphan-reclaim sweep at sign-in auto-claims the single-orphan case;
+* this endpoint backs the Settings "Claim install" buttons when there's
+* more than one (or the account is an org, where auto-claim is too risky).
+*/
+const githubAppInstallationClaimBodySchema = z.object({ installationId: z.number().int().positive() });
+z.object({
+	installationId: z.number().int().positive(),
+	accountType: githubAccountTypeSchema,
+	accountLogin: z.string(),
+	accountGithubId: z.number().int().positive(),
+	permissions: githubAppInstallationPermissionsSchema,
+	events: githubAppInstallationEventsSchema,
+	suspended: z.boolean(),
+	manageUrl: z.string().url(),
+	createdAt: z.string().datetime({ offset: true }),
+	updatedAt: z.string().datetime({ offset: true })
+});
 const supportedImageMimeSchema = z.enum([
 	"image/png",
 	"image/jpeg",
@@ -1199,18 +1295,36 @@ const notificationQuerySchema = z.object({
 const githubStartQuerySchema = z.object({ next: z.string().max(256).optional() });
 const githubCallbackQuerySchema = z.object({
 	code: z.string().min(1),
-	state: z.string().min(1)
+	state: z.string().min(1),
+	installation_id: z.string().regex(/^\d+$/).optional(),
+	setup_action: z.enum([
+		"install",
+		"update",
+		"request"
+	]).optional()
 });
 /**
 * Dev-only callback to bypass the GitHub round-trip — sign in as a stub
 * Github user. Gated by NODE_ENV !== 'production'; production always 404s.
+*
+* The App-flow extension fields (`installationId`, `installationAccountType`,
+* `installationAccountLogin`, `installationAccountGithubId`) let the dev
+* flow simulate a GitHub App install in the same redirect — when present
+* they stub a `github_app_installations` row before the OAuth flow
+* completes, so the rest of the dev session can exercise the App-bound
+* code paths (Settings → Integrations panel, webhook routing) without a
+* real install. Missing → legacy OAuth-only dev flow.
 */
 const githubDevCallbackQuerySchema = z.object({
 	githubId: z.string().min(1),
 	login: z.string().min(1),
 	email: z.string().email().optional(),
 	displayName: z.string().optional(),
-	next: z.string().max(256).optional()
+	next: z.string().max(256).optional(),
+	installationId: z.string().regex(/^\d+$/).optional(),
+	installationAccountType: z.enum(["User", "Organization"]).optional(),
+	installationAccountLogin: z.string().min(1).optional(),
+	installationAccountGithubId: z.string().regex(/^\d+$/).optional()
 });
 /**
 * Per-organization settings — schemas, namespaces, and the registry that
@@ -1606,4 +1720,4 @@ z.object({
 	capabilities: serverCapabilitiesSchema.optional()
 }).passthrough();
 //#endregion
-export { refreshTokenSchema as $, dryRunAgentRuntimeConfigSchema as A, isRedactedEnvValue as B, createAgentSchema as C, createOrgFromMeSchema as D, createMemberSchema as E, imageInlineContentSchema as F, messageSourceSchema as G, joinByInvitationSchema as H, inboxAckFrameSchema as I, paginationQuerySchema as J, notificationQuerySchema as K, inboxDeliverFrameSchema as L, githubCallbackQuerySchema as M, githubDevCallbackQuerySchema as N, defaultRuntimeConfigPayload as O, githubStartQuerySchema as P, rebindAgentSchema as Q, inboxPollQuerySchema as R, createAdapterMappingSchema as S, createMeChatSchema as T, listMeChatsQuerySchema as U, isReservedAgentName as V, loginSchema as W, questionAnswerMessageContentSchema as X, patchOnboardingSchema as Y, questionMessageContentSchema as Z, clientCapabilitiesSchema as _, updateClientCapabilitiesSchema as _t, AGENT_VISIBILITY as a, sendToAgentSchema as at, contextTreeSnapshotSchema as b, wsAuthFrameSchema as bt, ORG_SETTINGS_NAMESPACES as c, sessionEventSchema as ct, addParticipantSchema as d, stripCode as dt, runtimeStateMessageSchema as et, agentBindRequestSchema as f, submitQuestionAnswerSchema as ft, chatMetadataSchema as g, updateChatSchema as gt, agentTypeSchema as h, updateAgentSchema as ht, AGENT_STATUSES as i, sendMessageSchema as it, extractMentions as j, delegateFeishuUserSchema as k, WS_AUTH_FRAME_TIMEOUT_MS as l, sessionReconcileRequestSchema as lt, agentRuntimeConfigPayloadSchema as m, updateAgentRuntimeConfigSchema as mt, AGENT_NAME_REGEX as n, scanMentionTokens as nt, DEFAULT_RUNTIME_PROVIDER as o, sessionCompletionMessageSchema as ot, agentPinnedMessageSchema as p, updateAdapterConfigSchema as pt, onboardingEventSchema as q, AGENT_SELECTOR_HEADER as r, selfServiceFeishuBotSchema as rt, MENTION_REGEX as s, sessionEventMessageSchema as st, AGENT_BIND_REJECT_REASONS as t, safeRedirectPath as tt, addMeChatParticipantsSchema as u, sessionStateMessageSchema as ut, clientRegisterSchema as v, updateMemberSchema as vt, createChatSchema as w, createAdapterConfigSchema as x, connectTokenExchangeSchema as y, updateOrganizationSchema as yt, isOrgSettingNamespace as z };
+export { questionMessageContentSchema as $, delegateFeishuUserSchema as A, inboxPollQuerySchema as B, createAgentSchema as C, createOrgFromMeSchema as D, createMemberSchema as E, githubDevCallbackQuerySchema as F, listMeChatsQuerySchema as G, isRedactedEnvValue as H, githubStartQuerySchema as I, notificationQuerySchema as J, loginSchema as K, imageInlineContentSchema as L, extractMentions as M, githubAppInstallationClaimBodySchema as N, defaultParticipantMode as O, githubCallbackQuerySchema as P, questionAnswerMessageContentSchema as Q, inboxAckFrameSchema as R, createAdapterMappingSchema as S, wsAuthFrameSchema as St, createMeChatSchema as T, isReservedAgentName as U, isOrgSettingNamespace as V, joinByInvitationSchema as W, paginationQuerySchema as X, onboardingEventSchema as Y, patchOnboardingSchema as Z, clientCapabilitiesSchema as _, updateAgentSchema as _t, AGENT_VISIBILITY as a, selfServiceFeishuBotSchema as at, contextTreeSnapshotSchema as b, updateMemberSchema as bt, ORG_SETTINGS_NAMESPACES as c, sessionCompletionMessageSchema as ct, addParticipantSchema as d, sessionReconcileRequestSchema as dt, rebindAgentSchema as et, agentBindRequestSchema as f, sessionStateMessageSchema as ft, chatMetadataSchema as g, updateAgentRuntimeConfigSchema as gt, agentTypeSchema as h, updateAdapterConfigSchema as ht, AGENT_STATUSES as i, scanMentionTokens as it, dryRunAgentRuntimeConfigSchema as j, defaultRuntimeConfigPayload as k, WS_AUTH_FRAME_TIMEOUT_MS as l, sessionEventMessageSchema as lt, agentRuntimeConfigPayloadSchema as m, submitQuestionAnswerSchema as mt, AGENT_NAME_REGEX as n, runtimeStateMessageSchema as nt, DEFAULT_RUNTIME_PROVIDER as o, sendMessageSchema as ot, agentPinnedMessageSchema as p, stripCode as pt, messageSourceSchema as q, AGENT_SELECTOR_HEADER as r, safeRedirectPath as rt, MENTION_REGEX as s, sendToAgentSchema as st, AGENT_BIND_REJECT_REASONS as t, refreshTokenSchema as tt, addMeChatParticipantsSchema as u, sessionEventSchema as ut, clientRegisterSchema as v, updateChatSchema as vt, createChatSchema as w, createAdapterConfigSchema as x, updateOrganizationSchema as xt, connectTokenExchangeSchema as y, updateClientCapabilitiesSchema as yt, inboxDeliverFrameSchema as z };