Count direct Agent imports as App installations in a multi-tenant agent server

What they did

The author reworked how a multi-tenant agent platform decides whether an Agent counts as installed in an App. Instead of only reading physical AppAgent rows, direct required and optional AgentImport rows from a physically installed live parent in a live org App now count as derived installations. They built a shared source module (appInstallations.ts) that owns row/derived membership, reverse candidate predicates, and deciding witness locks, then migrated a long census of readers across casting, preview, change, role matching, roster, register, member roles, scopes, memory access, run readers, boot prompt pointers, MCP access control, and query resolvers to use it. Physical rows win over derived entries. Derived customization lazily creates keyed install memory, and a separate AppAgentCustomization record retains the App prompt pointer across target deletion. Existing staffing and App-holder license gates stay authoritative; the importing org's grant never substitutes. They kept the public installationKind/installMethod projection out of this change, deferring it to companion PRs. They ran a red-first workflow, committing failing tests before fixes, killed ten production guard mutants at intended assertions, and validated with 16 related suites/488 tests plus 7 guards, a full suite of 24560 tests passing, and hosted CI 15/15 green at a frozen commit. They also documented deferred P3s and left the issue open for companion reconciliation.

How it went

The change reached a frozen, CI-green state with a full suite exit 0 (24560 tests passing, 1 expected fail, 8 skips) and 15/15 hosted CI. Red-first history was retained, ten guard mutants were killed, and two real ROW membership regressions found in a superseded run were corrected. The PR remains a draft pending independent seat re-review; no merge, deploy, tag, or release authority was exercised, and fresh-stack/browser/production QA is still owed.

Worth knowing

The work is a draft awaiting independent cross-family review at the exact frozen head; prior review verdicts do not carry over. No fresh-stack, browser, or production claim is made. Public installationKind/installMethod projection is deferred to #3435/PR#3446, and several P3s (#3458, #3459) remain open. Some historical CI timeouts and a stale worker memoization failure have unconfirmed causes. The census is large and touches many readers, so regressions in physical-vs-derived precedence and audit nullability are the main risk areas.

Wiring

Start by building src/lib/appInstallations.ts as the single source for row/derived membership, reverse candidate predicates, and deciding witness locks. It reads real app_agents rows and derives membership from direct AgentImport rows whose parent is a physically installed live Agent in a live org App; it must never recurse through a derived parent and only locks/re-reads exact held witnesses. Then migrate readers in dependency order: workerCasting, worker resolvers, agentTickerTemplates, installMemory (schema and lib), compileBootPrompt, bootPromptPointer, memberRoles, resolvers.types roster, teamRole, teamChat/teamWork, register, actionRegisterIndex, mutation.appMemory, helpers, appAgent, prismaAuthDeps, appRelationship, appRuns, automationReadGrant, mcp/access-control, scopes, query.memory, query.app, query.chat, mutation.chat, agentChatAccess, joinApp, backfillChannels, sharedMemoryAdoption, agentPublicCongruence, and effectiveSystemMemory. Keep physical lifecycle paths (explicit install duplicate check, uninstall installedHere, getPrimaryAgentId, agentLiveReferences) on real rows. Add AppAgentCustomization for the derived prompt pointer and serialize pointer promotion with set/clear. Gate the public installMethod projection behind #3435/PR#3446. Run typecheck, related suites, guards, and the full suite at a frozen commit before requesting review.

Try it yourself

In this repo, make direct Agent imports count as App installations without writing AppAgent rows. Create a shared source module that owns physical-row and derived-import membership, reverse candidate predicates, and deciding witness locks. Derived means one direct AgentImport from a physically installed live parent in a live org App; required and optional both count; physical rows always win. Migrate every installation reader (casting, preview, change, role matching, roster, register, member roles, scopes, memory access, run readers, boot prompt pointers, MCP access control, query resolvers) to the shared source. Keep existing staffing and App-holder license gates authoritative. Lazily create derived install memory and keep the App prompt pointer on a separate customization record. Write red-first tests for physical/derived coexistence, deleted imports, license gates, audit nullability, and uninstall witness retention. Run the related suites and guards, then the full suite, and report exact-head CI status.