Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions layers/nuxi/AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Nuxi layer

Nuxi is an eve agent (`agent/`) plus the nuxt.com chat UI and APIs around it. Read `README.md` for setup, and the eve guide you need in `node_modules/eve/docs/` before changing agent code.

## Layout

- `agent/instructions.md`: the always-on prompt. Rules that apply to every turn: grounding, tools, citations, length, formatting.
- `agent/instructions/*.ts`: blocks that apply only sometimes (date, surface and caller, web preview, admin). Each returns `null` when it doesn't apply. Memoize anything async per turn with `ctx.memo(ctx.turn?.id ?? null, …)`.
- `agent/channels/`: who reaches Nuxi. `slack.ts` admits only full members of the home workspace, in every hook including `onAnswers`.
- `agent/lib/identity/`: `resolveContext` is the one source of truth for surface, person and channel; `admin-mode.ts` decides admin mode per surface.
- `agent/schedules/`: fixed cron workflows, plus `tasks.ts` for schedules people create in Slack.
- `evals/`: `eve eval` checks for the reply rules, with tools stubbed.

## Rules

- The agent never imports Nuxt server code. It calls `server/api/internal/*` over HTTP with `INTERNAL_API_SECRET`.
- Put company or ecosystem facts in tools, skills or connections, not in `instructions.md`.
- Keep access checks in the channel hooks and again inside any tool that reads or writes sensitive data (`assertAdminMode`).
- When you change reply behaviour in the instructions, add or update an eval under `evals/` and run it with `pnpm eval:nuxi <dir> --repeat 3`.
- Keep `evals/lib/slack.ts` in sync with `FOLLOWED_THREAD_GUIDANCE` in `agent/channels/slack.ts`.
31 changes: 30 additions & 1 deletion layers/nuxi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,36 @@ Auth uses the `nuxi-code` GitHub App on the `nuxt` org through the Vercel Connec

## Caller identity

`agent/lib/identity/context.ts` resolves `Context.person` (id, name, bot flag) for every surface, and `agent/lib/identity/caller-instructions.ts` renders it into the always-on prompt so "who am I?" has an answer. Discord's display name (`global_name`) comes for free from the inbound message payload; the `@`-mention handle (`username`) is still kept on the auth context for future use, it's just not what the model sees. Slack's `app_mention`/`message` events only carry a user id — `channels/slack.ts` resolves the real name via `users.info` (`agent/lib/slack/api.ts`, cached 1h per user), which needs the **`users:read`** bot scope on top of the ones above; without it, Slack callers fall back to their user id.
`agent/lib/identity/context.ts` resolves `Context.person` (id, name, bot flag) for every surface, and `agent/lib/identity/caller-instructions.ts` renders it into the always-on prompt so "who am I?" has an answer. Discord's display name (`global_name`) comes for free from the inbound message payload; the `@`-mention handle (`username`) is still kept on the auth context for future use, it's just not what the model sees. Slack's `app_mention`/`message` events only carry a user id: the Slack access check below looks the sender up with `users.info` and passes their display name along.

## Slack access and threads

Every Slack caller gets admin mode, so `agent/channels/slack.ts` admits only **full members of the home workspace**: `agent/lib/slack/members.ts` rejects guests (`is_restricted`, `is_ultra_restricted`), deactivated accounts and, when `SLACK_TEAM_ID` is set on the eve service, Slack Connect users from other workspaces. One `users.info` call (cached 10 minutes) gives both the decision and the caller's name. A failed lookup drops the message instead of letting it through. `onAnswers` applies the same check to approval and question clicks, so a guest can't approve a `coder` change in a member's thread. Other apps' bots still reach Nuxi from the home workspace but never get admin mode.

Nuxi also **follows threads it's part of**: a reply without a mention in such a thread reaches it with `status: 'deferred'` and a guidance line, and Nuxi calls `no_reply` (`agent/tools/no_reply.ts`) when the reply is for someone else. Top-level messages still need a mention.

Connector settings (`slack/nuxi` and `slack/nuxi-preview`, **Advanced**):

- **Trigger Event Types:** `message.channels` and `message.groups`, for followed threads.
- **Bot Scopes:** `users:read` (access check, required: without it nobody gets through), `channels:history` and `groups:history` (followed threads), `search:read.public` (`search_slack`), `channels:read`, `groups:read`, `im:read` and `mpim:read` (scheduled tasks check the destination conversation with `conversations.info` before each run, which needs the read scope of its type).

`agent/tools/search_slack.ts` searches public channels with Slack's [Real-time Search API](https://docs.slack.dev/apis/web-api/real-time-search-api), on Slack and in admin mode only. It uses the per-message `action_token`, so it works only in a turn a mention or DM started.

## Scheduled tasks

`agent/schedules/tasks.ts` uses eve's experimental [dynamic schedules](https://eve.dev/docs/experimental/dynamic-schedules): people ask Nuxi in Slack for recurring or one-time tasks ("every Monday at 9am Paris time, post open showcase candidates here"), and it calls the deferred `schedule__tasks__*` tools. The destination channel, thread and creator come from the Slack session, never from the model. Each person manages only their own schedules, from Slack only, and creating or changing one asks for approval. Before each run, Nuxi checks the creator is still a full member and still in the channel, and disables the schedule otherwise. Under `eve dev` schedules never fire on their own; ask Nuxi to run one now (`invoke`). Fixed workflows stay in code, below.

## Evals

`evals/` checks the reply rules in `agent/instructions.md` against the real model, with tools such as `search_docs` replaced by fixed results (`allowToolStubs`, granted to the local `eve dev` caller only in `agent/channels/eve.ts`):

```sh
pnpm eval:nuxi # every eval
pnpm eval:nuxi threads # one directory
pnpm eval:nuxi --repeat 3 # results vary; repeat before trusting a prompt change
```

They need only AI Gateway access. When you change reply behaviour in the instructions, add or update a case.

## Data retention

Expand Down
2 changes: 1 addition & 1 deletion layers/nuxi/agent/channels/discord.ts
Original file line number Diff line number Diff line change
Expand Up @@ -286,7 +286,7 @@ function createDiscordBridge() {
}

// Discord-specific behaviour lives in the always-on prompt, keyed on the
// principal (`lib/surface-instructions.ts`) — passing it as `context` here
// principal (`lib/identity/surface-instructions.ts`) — passing it as `context` here
// would prepend a fresh copy to history on every message.
await send(
toMessageContent(turn),
Expand Down
15 changes: 13 additions & 2 deletions layers/nuxi/agent/channels/eve.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import { timingSafeEqual } from 'node:crypto'
import type { AuthFn } from 'eve/channels/auth'
import { localDev, vercelOidc } from 'eve/channels/auth'
import { defaultEveAuth, eveChannel } from 'eve/channels/eve'
import { defaultEveAuth, eveChannel, type EveAuthFn } from 'eve/channels/eve'
import { checkBotId } from 'botid/server'
import { appFetch, internalHeaders } from '../lib/internal-api.js'
import { anonymousIpKey, clientIp } from '../../shared/utils/rate-limit.js'
Expand Down Expand Up @@ -79,11 +79,22 @@ function nuxtServerAuth(): AuthFn<Request> {
}
}

const localDevAuth = localDev()

/**
* `evals/` replace tools such as `search_docs` with fixed results, which needs `allowToolStubs`.
* `localDev()` admits callers only on a local `eve dev` server, so deployments never grant it.
*/
const localDevWithStubs: EveAuthFn = async (request) => {
const caller = await localDevAuth(request)
return caller ? { ...caller, allowToolStubs: true } : null
}

export default eveChannel({
auth: [
nuxtSessionAuth(),
nuxtServerAuth(),
localDev(),
localDevWithStubs,
vercelOidc()
],
// Anything scoped to a single turn (the page the user has open) rides on
Expand Down
79 changes: 61 additions & 18 deletions layers/nuxi/agent/channels/slack.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,11 @@ import {
defineSlackRenderer,
slackChannel,
type SlackContext,
type SlackInboundMessageContext,
type SlackMessage
} from 'eve/channels/slack'
import { resolveSlackUserName } from '../lib/slack/api.js'
import { slackConnectorId } from '../lib/slack/connect.js'
import { findFullSlackMember, isHomeSlackTeam } from '../lib/slack/members.js'

function isHookConflictFailure(event: { code?: string, message?: string }) {
const message = event.message ?? ''
Expand All @@ -16,25 +17,60 @@ function isHookConflictFailure(event: { code?: string, message?: string }) {
|| message.includes('already in use by another workflow')
}

// Slack-specific behaviour lives in the always-on prompt, keyed on the
// principal (`lib/surface-instructions.ts`). Returning it as channel `context`
// would prepend a fresh copy to history on every mention.
//
// `app_mention`/`message` events only carry a user id, so resolve the real
// name here (cached) for `context.ts`'s `person.name`. Bots have none to look up.
async function dispatchSlackMessage(ctx: SlackContext, message: SlackMessage) {
// Slack Connect events name the author's own workspace in `user_team` or `team`. Same-workspace
// events can omit both, and then the envelope's team is the author's.
function authorTeamId(message: SlackMessage): string | undefined {
const { user_team: userTeam, team } = message.raw
if (typeof userTeam === 'string') return userTeam
return typeof team === 'string' ? team : message.teamId
}

/**
* Every Slack caller gets admin mode (`lib/identity/admin-mode.ts`), so only full members of the
* home workspace reach Nuxi: no guests, no Slack Connect users, no deactivated accounts. Other
* apps' bots pass only from the home workspace, and never get admin mode. A failed lookup drops
* the message (fail closed).
*
* Slack-specific behaviour lives in the always-on prompt (`instructions/surface.ts`); returning
* it as channel `context` would prepend a fresh copy to history on every mention.
*/
async function admit(ctx: SlackContext, message: SlackMessage) {
const author = message.author
if (!author || !isHomeSlackTeam(authorTeamId(message))) return null
const auth = defaultSlackAuth(message, ctx)
if (!auth) return null
if (author.isBot) return { auth }

const userId = message.author?.userId
if (!auth.attributes.full_name && userId && !message.author?.isBot) {
const fullName = await resolveSlackUserName(userId)
if (fullName) {
return { auth: { ...auth, attributes: { ...auth.attributes, full_name: fullName } } }
}
}
const member = await findFullSlackMember(author.userId)
if (!member) return null
// `app_mention`/`message` events only carry a user id; `context.ts` reads the name from here.
if (auth.attributes.full_name || !member.name) return { auth }
return { auth: { ...auth, attributes: { ...auth.attributes, full_name: member.name } } }
}

/** Kept in sync with `evals/lib/slack.ts`, which sends the same guidance over HTTP. */
export const FOLLOWED_THREAD_GUIDANCE
= 'You are part of this Slack thread, so you see replies people send each other. This reply '
+ 'doesn\'t mention you. Answer only if it\'s meant for you or you can clearly help; otherwise '
+ 'call `no_reply`.'

/**
* Un-mentioned messages: code channel messages (every one is for Nuxi), and replies in a thread
* Nuxi is already part of. Top-level channel messages still need a mention, and other bots never
* get here, so two bots can't loop. Needs the `message.channels` event and `channels:history`
* scope (`message.groups` and `groups:history` for private channels) on the connector.
*/
async function onMessage(ctx: SlackInboundMessageContext, message: SlackMessage) {
if (message.author?.isBot !== false) return null
if (ctx.slack.codeChannel) return admit(ctx, message)

// An edit only reaches a thread that already has a session.
const followed = ctx.edit !== undefined
|| (message.threadTs !== message.ts && await ctx.isSubscribed())
if (!followed) return null

return { auth }
const admitted = await admit(ctx, message)
return admitted && { ...admitted, status: 'deferred' as const, guidance: FOLLOWED_THREAD_GUIDANCE }
}

const sessionFailure = defineSlackRenderer({
Expand All @@ -59,7 +95,14 @@ export default slackChannel({
// mention. `tools/open_code_channel.ts` moves coding requests into one.
codeChannels: true,
threadContext: { since: 'last-agent-reply' },
onAppMention: dispatchSlackMessage,
onDirectMessage: dispatchSlackMessage,
onAppMention: admit,
onDirectMessage: admit,
onMessage,
// The same gate for approval and question clicks, so a guest in a thread a member started
// can't approve a `coder` pull request update.
async onAnswers(ctx, submission) {
const member = await findFullSlackMember(submission.user.id)
return member ? { auth: ctx.defaultAuth } : null
},
renderers: [sessionFailure]
})
Loading
Loading