@oxygen-agent/cli 1.1014.135 → 1.1014.618

package/node_modules/@oxygen/shared/dist/teammate-routines.js

@@ -0,0 +1,266 @@
+// AI teammates (ADR 0032): routines.
+//
+// A routine is something a teammate does for one person on a schedule ("every
+// weekday at 9, look at the campaign and tell me what changed"), held as an
+// ongoing Agent session that belongs to the teammate and to the person who set
+// it up from their chat with it: its settings carry `teammate_routine`, the
+// chat its reports post into. Each wake is an unattended run as that person,
+// within the caps they approved. It posts into the chat only when it has
+// something new to say, and an approval it raises is theirs alone and expires.
+//
+// The teammate proposes one; the proposal ENDS the turn, the way a question
+// card does, and the person sets it up from a card through the ordinary session
+// routes (create, preview, activate), which is their approval of exactly that
+// schedule, scope and caps. Nothing is scheduled on the model's word alone.
+//
+// One owner for the contract, because four readers depend on it: the tool that
+// validates the model's proposal, the session read that projects the pending
+// one, the card that sets it up, and the routes that hold it. The proposal is
+// kept in its wire shape (the tool's own input, plus an id), so what the tool
+// stores is exactly what the projection reads back.
+import { EMPTY_AGENT_SESSION_RESOURCES } from "./agent-sessions.js";
+import { describeAgentSessionSchedule } from "./agent-session-schedule.js";
+import { isCronSyntax } from "./schedule-label.js";
+import { isValidTimeZone } from "./zoned-time.js";
+export const TEAMMATE_PROPOSE_ROUTINE_TOOL_NAME = "propose_routine";
+/** The runtime tool a routine's run reports into its creator's chat with. */
+export const TEAMMATE_ROUTINE_POST_UPDATE_TOOL_NAME = "post_update";
+/**
+ * How long an unattended teammate run (a routine's or a background task's)
+ * waits for its person to decide an approval. Then the approval expires, the
+ * run stops, and the chat says so; nothing waits on a person indefinitely.
+ */
+export const TEAMMATE_UNATTENDED_APPROVAL_TTL_MINUTES = 60;
+export const TEAMMATE_ROUTINE_LIMITS = {
+    nameChars: 80,
+    goalChars: 4_000,
+    whyChars: 300,
+    /** One report a run posts; a longer one belongs on a Knowledge page or a record. */
+    reportChars: 4_000,
+    /** The most often a proposed interval routine runs. A cron one runs at most hourly: one fixed minute. */
+    minIntervalMinutes: 15,
+    maxIntervalMinutes: 10_080,
+    maxPerRunCredits: 2_000,
+    maxDailyCredits: 20_000,
+    resourcesPerKind: 20,
+};
+const RESOURCE_KINDS = Object.keys(EMPTY_AGENT_SESSION_RESOURCES);
+/** The tool's input schema, as the model reads it. */
+export const TEAMMATE_PROPOSE_ROUTINE_INPUT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        name: {
+            type: "string",
+            minLength: 1,
+            maxLength: TEAMMATE_ROUTINE_LIMITS.nameChars,
+            description: "A short name, e.g. \"Monday pipeline review\".",
+        },
+        goal: {
+            type: "string",
+            minLength: 1,
+            maxLength: TEAMMATE_ROUTINE_LIMITS.goalChars,
+            description: "What each run does without this chat: what to check, what is worth reporting, and what to leave alone.",
+        },
+        schedule: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                kind: { type: "string", enum: ["interval", "cron"] },
+                every_minutes: {
+                    type: "integer",
+                    minimum: TEAMMATE_ROUTINE_LIMITS.minIntervalMinutes,
+                    maximum: TEAMMATE_ROUTINE_LIMITS.maxIntervalMinutes,
+                    description: "interval: minutes between runs.",
+                },
+                cron: { type: "string", description: "cron: five fields with one fixed minute, e.g. \"0 9 * * 1-5\" for weekdays at 09:00." },
+                timezone: { type: "string", description: "cron: the person's IANA time zone, e.g. Europe/Berlin." },
+            },
+            required: ["kind"],
+        },
+        per_run_credits: {
+            type: "integer",
+            minimum: 1,
+            maximum: TEAMMATE_ROUTINE_LIMITS.maxPerRunCredits,
+            description: "The most one run may spend, including inference.",
+        },
+        daily_credits: {
+            type: "integer",
+            minimum: 1,
+            maximum: TEAMMATE_ROUTINE_LIMITS.maxDailyCredits,
+            description: "The most its runs may spend in any 24 hours; at least per_run_credits.",
+        },
+        resources: {
+            type: "object",
+            additionalProperties: false,
+            properties: Object.fromEntries(RESOURCE_KINDS.map((kind) => [kind, {
+                    type: "array", items: { type: "string" }, maxItems: TEAMMATE_ROUTINE_LIMITS.resourcesPerKind,
+                }])),
+            description: "Exact IDs or slugs each run may read: sequences (campaigns), tables, conversations, mailboxes, records, objects (CRM objects such as deals), knowledge (page slugs), domains.",
+        },
+        why: {
+            type: "string",
+            maxLength: TEAMMATE_ROUTINE_LIMITS.whyChars,
+            description: "One line on why this should run on a schedule.",
+        },
+    },
+    required: ["name", "goal", "schedule", "per_run_credits", "daily_credits"],
+};
+const clean = (value, max) => typeof value === "string" ? value.replace(/\s+/g, " ").trim().slice(0, max) : "";
+const wholeNumber = (value) => (typeof value === "number" && Number.isInteger(value) ? value : NaN);
+function normalizeSchedule(value) {
+    const schedule = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+    if (schedule.kind === "cron") {
+        const cron = typeof schedule.cron === "string" ? schedule.cron.trim().replace(/\s+/g, " ") : "";
+        // One fixed minute keeps a cron routine to at most one run an hour; "every
+        // N minutes" is what an interval routine is for.
+        if (!isCronSyntax(cron) || !/^\d{1,2}$/.test(cron.split(" ")[0] ?? "") || Number(cron.split(" ")[0]) > 59) {
+            return { ok: false, message: "schedule.cron must be five cron fields with one fixed minute, e.g. \"0 9 * * 1-5\"." };
+        }
+        const timezone = typeof schedule.timezone === "string" ? schedule.timezone.trim() : "";
+        if (!isValidTimeZone(timezone))
+            return { ok: false, message: "schedule.timezone must be an IANA time zone, e.g. Europe/Berlin." };
+        return { ok: true, value: { kind: "cron", cron, timezone } };
+    }
+    if (schedule.kind === "interval") {
+        const every = wholeNumber(schedule.every_minutes);
+        if (!(every >= TEAMMATE_ROUTINE_LIMITS.minIntervalMinutes && every <= TEAMMATE_ROUTINE_LIMITS.maxIntervalMinutes)) {
+            return {
+                ok: false,
+                message: `schedule.every_minutes must be a whole number from ${TEAMMATE_ROUTINE_LIMITS.minIntervalMinutes} to ${TEAMMATE_ROUTINE_LIMITS.maxIntervalMinutes}.`,
+            };
+        }
+        return { ok: true, value: { kind: "interval", every_minutes: every } };
+    }
+    return { ok: false, message: "schedule.kind must be interval (every_minutes) or cron (cron and timezone)." };
+}
+function normalizeResources(value) {
+    if (value === undefined || value === null)
+        return { ok: true, value: {} };
+    if (typeof value !== "object" || Array.isArray(value))
+        return { ok: false, message: "resources must map resource kinds to ID or slug lists." };
+    const resources = {};
+    for (const [kind, refs] of Object.entries(value)) {
+        if (!RESOURCE_KINDS.includes(kind))
+            return { ok: false, message: `resources.${kind} is not a resource kind.` };
+        if (!Array.isArray(refs) || refs.length > TEAMMATE_ROUTINE_LIMITS.resourcesPerKind) {
+            return { ok: false, message: `resources.${kind} must list at most ${TEAMMATE_ROUTINE_LIMITS.resourcesPerKind} IDs or slugs.` };
+        }
+        const exact = refs.map((ref) => (typeof ref === "string" ? ref.trim() : ""));
+        if (exact.some((ref) => !ref || ref.includes(",") || ref === "*")) {
+            return { ok: false, message: `resources.${kind} takes exact IDs or slugs, never a wildcard.` };
+        }
+        if (exact.length > 0)
+            resources[kind] = [...new Set(exact)];
+    }
+    return { ok: true, value: resources };
+}
+/** Validate a proposal the model made, minting its id. */
+export function normalizeTeammateRoutineProposal(args, mintId) {
+    const name = clean(args.name, TEAMMATE_ROUTINE_LIMITS.nameChars);
+    const goal = typeof args.goal === "string" ? args.goal.trim().slice(0, TEAMMATE_ROUTINE_LIMITS.goalChars) : "";
+    if (!name)
+        return { ok: false, message: "A routine needs a name." };
+    if (!goal)
+        return { ok: false, message: "A routine needs a goal each run can work from alone." };
+    const schedule = normalizeSchedule(args.schedule);
+    if (!schedule.ok)
+        return schedule;
+    const perRun = wholeNumber(args.per_run_credits);
+    const daily = wholeNumber(args.daily_credits);
+    if (!(perRun >= 1 && perRun <= TEAMMATE_ROUTINE_LIMITS.maxPerRunCredits)) {
+        return { ok: false, message: `per_run_credits must be a whole number from 1 to ${TEAMMATE_ROUTINE_LIMITS.maxPerRunCredits}.` };
+    }
+    if (!(daily >= perRun && daily <= TEAMMATE_ROUTINE_LIMITS.maxDailyCredits)) {
+        return { ok: false, message: `daily_credits must be a whole number from per_run_credits to ${TEAMMATE_ROUTINE_LIMITS.maxDailyCredits}.` };
+    }
+    const resources = normalizeResources(args.resources);
+    if (!resources.ok)
+        return resources;
+    const why = clean(args.why, TEAMMATE_ROUTINE_LIMITS.whyChars);
+    return {
+        ok: true,
+        proposal: {
+            id: mintId(), name, goal, schedule: schedule.value, per_run_credits: perRun, daily_credits: daily,
+            resources: resources.value, why: why || null,
+        },
+    };
+}
+/** Read a stored proposal back, refusing anything malformed. */
+export function readTeammateRoutineProposal(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    if (typeof record.id !== "string" || !record.id || record.id.length > 64)
+        return null;
+    const normalized = normalizeTeammateRoutineProposal(record, () => record.id);
+    return normalized.ok ? normalized.proposal : null;
+}
+/** The routine's schedule as a session reads it. */
+export function teammateRoutineSessionSchedule(schedule) {
+    // A routine runs on the schedule its person approved, so its interval bounds
+    // are the interval itself: the run never moves its own next wake.
+    return schedule.kind === "cron"
+        ? { kind: "cron", cron: schedule.cron, timezone: schedule.timezone }
+        : { kind: "interval", interval_minutes: schedule.every_minutes, min_interval_minutes: schedule.every_minutes, max_interval_minutes: schedule.every_minutes };
+}
+/**
+ * The exact session settings the card creates for a proposal: a custom job
+ * with scoped reads only (writes ask the person each time), no events, and the
+ * marker that binds it to the person's chat.
+ */
+export function teammateRoutineSessionConfig(proposal, chatId) {
+    return {
+        title: proposal.name,
+        goal: proposal.goal,
+        template: "custom",
+        resources: Object.fromEntries(RESOURCE_KINDS.map((kind) => [kind, [...(proposal.resources[kind] ?? [])]])),
+        actions: [],
+        events: [],
+        schedule: teammateRoutineSessionSchedule(proposal.schedule),
+        budget: { per_run_credits: proposal.per_run_credits, daily_credits: proposal.daily_credits },
+        teammate_routine: { chat_id: chatId, proposal_id: proposal.id },
+    };
+}
+/** The proposal as the turn's reply: what the CLI and MCP print, and what the next turn reads back. */
+export function renderTeammateRoutineProposalText(proposal) {
+    const schedule = describeAgentSessionSchedule(teammateRoutineSessionSchedule(proposal.schedule));
+    return [
+        `I can set this up as a routine: **${proposal.name}**, ${schedule}, up to ${proposal.per_run_credits} credits a run and ${proposal.daily_credits} in any 24 hours.`,
+        ...(proposal.why ? [proposal.why] : []),
+        "It runs as you and posts here only when there is something new. Set it up from the card, or tell me what to change.",
+    ].join("\n\n");
+}
+/**
+ * The silence rule's comparison: a report that says what the routine's last
+ * report said, give or take whitespace, is not posted again.
+ */
+export function sameTeammateRoutineReport(left, right) {
+    const flat = (text) => text.replace(/\s+/g, " ").trim();
+    return flat(left) === flat(right);
+}
+/**
+ * The routine proposal the chat is waiting on, or null. Like a question, only
+ * the newest turn can be waiting, and only when it completed by proposing; a
+ * proposal already set up (its id among `startedIds`) is not waiting.
+ */
+export function projectPendingTeammateRoutineProposal(input) {
+    const newest = input.turns.reduce((latest, turn) => (latest === null || turn.turnIndex > latest.turnIndex ? turn : latest), null);
+    if (!newest || newest.status !== "completed")
+        return null;
+    for (let index = input.events.length - 1; index >= 0; index -= 1) {
+        const event = input.events[index];
+        if (!event || event.turnId !== newest.id || event.kind !== "tool_call_finished")
+            continue;
+        if (event.payload.tool !== TEAMMATE_PROPOSE_ROUTINE_TOOL_NAME)
+            continue;
+        const result = event.payload.result;
+        if (!result || typeof result !== "object" || result.ok === false)
+            continue;
+        const proposal = readTeammateRoutineProposal(result.proposal);
+        if (!proposal || input.startedIds.has(proposal.id))
+            return null;
+        return { ...proposal, turn_id: newest.id };
+    }
+    return null;
+}

package/node_modules/@oxygen/shared/dist/teammate-tasks.d.ts

@@ -0,0 +1,56 @@
+export declare const TEAMMATE_PROPOSE_TASK_TOOL_NAME = "propose_background_task";
+export declare const TEAMMATE_TASK_LIMITS: {
+    readonly titleChars: 80;
+    readonly goalChars: 4000;
+    readonly whyChars: 300;
+    /** The highest ceiling a proposal may carry; a bigger job is several tasks. */
+    readonly maxCredits: 2000;
+    /** Background tasks one chat may have running at once. */
+    readonly activePerChat: 3;
+};
+export type TeammateTaskProposal = {
+    id: string;
+    title: string;
+    goal: string;
+    maxCredits: number;
+    why: string | null;
+};
+/** The proposal a chat is waiting on, as every surface reads it. */
+export type PendingTeammateTaskProposal = TeammateTaskProposal & {
+    turnId: string;
+};
+/** The tool's input schema, as the model reads it. */
+export declare const TEAMMATE_PROPOSE_TASK_INPUT_SCHEMA: Record<string, unknown>;
+/** Validate a proposal the model made, minting its id. */
+export declare function normalizeTeammateTaskProposal(args: Record<string, unknown>, mintId: () => string): {
+    ok: true;
+    proposal: TeammateTaskProposal;
+} | {
+    ok: false;
+    message: string;
+};
+/** The proposal as the turn's reply: what the CLI and MCP print, and what the next turn reads back. */
+export declare function renderTeammateTaskProposalText(proposal: TeammateTaskProposal): string;
+/** Read a stored proposal back, refusing anything malformed. */
+export declare function readTeammateTaskProposal(value: unknown): TeammateTaskProposal | null;
+type ProjectionTurn = {
+    id: string;
+    status: string;
+    turnIndex: number;
+};
+type ProjectionEvent = {
+    turnId: string | null;
+    kind: string;
+    payload: Record<string, unknown>;
+};
+/**
+ * The proposal the chat is waiting on, or null. Like a question, only the
+ * newest turn can be waiting, and only when it completed by proposing; a
+ * proposal already started (its id among `startedIds`) is not waiting.
+ */
+export declare function projectPendingTeammateTaskProposal(input: {
+    turns: readonly ProjectionTurn[];
+    events: readonly ProjectionEvent[];
+    startedIds: ReadonlySet<string>;
+}): PendingTeammateTaskProposal | null;
+export {};

package/node_modules/@oxygen/shared/dist/teammate-tasks.js

@@ -0,0 +1,114 @@
+// AI teammates (ADR 0032): background tasks.
+//
+// In a teammate chat the teammate can propose to run something in the
+// background instead of making the person wait for it: an unattended run of
+// the teammate's own published Agent, with a goal and a credit ceiling. The
+// proposal ENDS the turn, the way a question card does; the person starts it
+// from a card (or `oxygents task` on the CLI and MCP), which is the approval:
+// the run acts as them, within the ceiling they accepted, and its result is
+// posted back into the chat. Nothing starts on the model's word alone.
+//
+// One owner for the contract, because four readers depend on it: the tool that
+// validates the model's proposal, the session read that projects the pending
+// one, the card that starts it, and the route that turns it into a run.
+export const TEAMMATE_PROPOSE_TASK_TOOL_NAME = "propose_background_task";
+export const TEAMMATE_TASK_LIMITS = {
+    titleChars: 80,
+    goalChars: 4_000,
+    whyChars: 300,
+    /** The highest ceiling a proposal may carry; a bigger job is several tasks. */
+    maxCredits: 2_000,
+    /** Background tasks one chat may have running at once. */
+    activePerChat: 3,
+};
+/** The tool's input schema, as the model reads it. */
+export const TEAMMATE_PROPOSE_TASK_INPUT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        title: {
+            type: "string",
+            minLength: 1,
+            maxLength: TEAMMATE_TASK_LIMITS.titleChars,
+            description: "A short name for the task, e.g. \"Research 40 fintech accounts\".",
+        },
+        goal: {
+            type: "string",
+            minLength: 1,
+            maxLength: TEAMMATE_TASK_LIMITS.goalChars,
+            description: "Everything the run needs to do the work without this chat: the outcome, scope, inputs and where to put results.",
+        },
+        max_credits: {
+            type: "integer",
+            minimum: 1,
+            maximum: TEAMMATE_TASK_LIMITS.maxCredits,
+            description: "The most the run may spend, including inference. The person approves exactly this ceiling.",
+        },
+        why: {
+            type: "string",
+            maxLength: TEAMMATE_TASK_LIMITS.whyChars,
+            description: "One line on why this should run in the background rather than now.",
+        },
+    },
+    required: ["title", "goal", "max_credits"],
+};
+const clean = (value, max) => typeof value === "string" ? value.replace(/\s+/g, " ").trim().slice(0, max) : "";
+/** Validate a proposal the model made, minting its id. */
+export function normalizeTeammateTaskProposal(args, mintId) {
+    const title = clean(args.title, TEAMMATE_TASK_LIMITS.titleChars);
+    const goal = typeof args.goal === "string" ? args.goal.trim().slice(0, TEAMMATE_TASK_LIMITS.goalChars) : "";
+    const maxCredits = typeof args.max_credits === "number" && Number.isInteger(args.max_credits) ? args.max_credits : NaN;
+    if (!title)
+        return { ok: false, message: "A background task needs a title." };
+    if (!goal)
+        return { ok: false, message: "A background task needs a goal the run can work from alone." };
+    if (!(maxCredits >= 1 && maxCredits <= TEAMMATE_TASK_LIMITS.maxCredits)) {
+        return { ok: false, message: `max_credits must be a whole number from 1 to ${TEAMMATE_TASK_LIMITS.maxCredits}.` };
+    }
+    const why = clean(args.why, TEAMMATE_TASK_LIMITS.whyChars);
+    return { ok: true, proposal: { id: mintId(), title, goal, maxCredits, why: why || null } };
+}
+/** The proposal as the turn's reply: what the CLI and MCP print, and what the next turn reads back. */
+export function renderTeammateTaskProposalText(proposal) {
+    return [
+        `I can run this in the background: **${proposal.title}**, up to ${proposal.maxCredits} credits.`,
+        ...(proposal.why ? [proposal.why] : []),
+        "It runs as you and its result posts here. Start it from the card, or tell me to do it differently.",
+    ].join("\n\n");
+}
+/** Read a stored proposal back, refusing anything malformed. */
+export function readTeammateTaskProposal(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    if (typeof record.id !== "string" || !record.id)
+        return null;
+    // The tool result keeps the normalized proposal, whose ceiling is `maxCredits`.
+    const normalized = normalizeTeammateTaskProposal({ ...record, max_credits: record.maxCredits ?? record.max_credits }, () => record.id);
+    return normalized.ok ? normalized.proposal : null;
+}
+/**
+ * The proposal the chat is waiting on, or null. Like a question, only the
+ * newest turn can be waiting, and only when it completed by proposing; a
+ * proposal already started (its id among `startedIds`) is not waiting.
+ */
+export function projectPendingTeammateTaskProposal(input) {
+    const newest = input.turns.reduce((latest, turn) => (latest === null || turn.turnIndex > latest.turnIndex ? turn : latest), null);
+    if (!newest || newest.status !== "completed")
+        return null;
+    for (let index = input.events.length - 1; index >= 0; index -= 1) {
+        const event = input.events[index];
+        if (!event || event.turnId !== newest.id || event.kind !== "tool_call_finished")
+            continue;
+        if (event.payload.tool !== TEAMMATE_PROPOSE_TASK_TOOL_NAME)
+            continue;
+        const result = event.payload.result;
+        if (!result || typeof result !== "object" || result.ok === false)
+            continue;
+        const proposal = readTeammateTaskProposal(result.proposal);
+        if (!proposal || input.startedIds.has(proposal.id))
+            return null;
+        return { ...proposal, turnId: newest.id };
+    }
+    return null;
+}

package/node_modules/@oxygen/shared/dist/teammates.d.ts

@@ -0,0 +1,78 @@
+/**
+ * AI teammates (ADR 0032): Agents the whole workspace talks to, each person in
+ * one ongoing private chat per teammate, on the Copilot runtime.
+ *
+ * Staff-only on dev. `OXYGEN_TEAMMATES_ENABLED` is the switch; when it is
+ * unset the feature follows the Ongoing Agent sessions staff gate, which the
+ * dev web and worker already receive, because teammates re-scope those
+ * sessions into routines. Production and shadow never qualify.
+ */
+export declare function teammatesEnabled(env?: Record<string, string | undefined>): boolean;
+export declare function teammatesAvailableTo(env: Record<string, string | undefined>, viewer: {
+    email: string | null | undefined;
+    member: boolean;
+    oxygenRole?: string | null | undefined;
+}): boolean;
+/**
+ * The Workspace Agent's slug. Every workspace's first Oxygent is that Agent: an
+ * Oxygent like the others, first in the list and where Home opens, with no role
+ * of its own (Tim, 2026-10-13: "The default agent should be Oxygent and not
+ * Chief of Staff").
+ */
+export declare const DEFAULT_TEAMMATE_SLUG = "workspace";
+/** What an Oxygent is called until someone names it, as Grok Bot's are (Tim, 2026-10-13). */
+export declare const NEW_TEAMMATE_NAME = "New Bot";
+export declare const TEAMMATE_NAME_MAX_CHARS = 80;
+export declare const TEAMMATE_DESCRIPTION_MAX_CHARS = 500;
+/**
+ * An Oxygent's look, picked like a Grok Bot bot's (Tim, 2026-10-13): one of
+ * these shapes, each a little molecule of round atoms with eyes, in one of
+ * these colours. The web draws them; anything else stored reads as unset.
+ */
+export declare const TEAMMATE_AVATAR_KEYS: readonly ["o2", "atom", "twin", "tripod", "mark", "clover", "trio", "bubbles", "crown", "orbit", "comet", "pill"];
+export type TeammateAvatarKey = typeof TEAMMATE_AVATAR_KEYS[number];
+export declare const TEAMMATE_AVATAR_COLORS: readonly ["forest", "brown", "red", "orange", "amber", "green", "aqua", "blue", "violet", "purple", "magenta", "slate"];
+export type TeammateAvatarColor = typeof TEAMMATE_AVATAR_COLORS[number];
+export declare function isTeammateAvatarKey(value: unknown): value is TeammateAvatarKey;
+export declare function isTeammateAvatarColor(value: unknown): value is TeammateAvatarColor;
+/**
+ * The look an Oxygent wears until someone picks one: the first Oxygent wears
+ * OXYGEN's own (an O2 molecule in forest green); any other one a look its slug
+ * picks, so a new one never arrives looking like the last.
+ */
+export declare function teammateDefaultLook(slug: string): {
+    avatarKey: TeammateAvatarKey;
+    avatarColor: TeammateAvatarColor;
+};
+/**
+ * How an Oxygent presents: its name, what it does and its look. The first
+ * Oxygent is "New Bot" until its owner names it; nothing renames the stored
+ * Agent to get there, and the Workspace Agent's stock description is no job.
+ */
+export declare function teammatePresentation(agent: {
+    slug: string;
+    name: string;
+    description?: string | null;
+    avatarKey?: string | null;
+    avatarColor?: string | null;
+}): {
+    name: string;
+    description: string;
+    avatarKey: TeammateAvatarKey;
+    avatarColor: TeammateAvatarColor;
+};
+/** How much of a teammate's latest words its roster row shows. */
+export declare const TEAMMATE_PREVIEW_MAX_CHARS = 140;
+/**
+ * One line of a teammate's latest words, for its roster row: the markdown
+ * reduced to its text, whitespace collapsed, cut at a word near `maxChars`.
+ */
+export declare function teammatePreviewLine(text: string, maxChars?: number): string;
+/** A handle made from a teammate's name ("Lead Scout" → "lead-scout"); null when nothing usable is left. */
+export declare function teammateSlugFromName(name: string): string | null;
+/**
+ * The first instructions of an Oxygent added from the sidebar or the CLI. They
+ * name no name and no job: the chat's role block says both from the profile,
+ * which its owner edits at any time, where a published version would go stale.
+ */
+export declare const TEAMMATE_STARTER_INSTRUCTIONS: string;

package/node_modules/@oxygen/shared/dist/teammates.js

@@ -0,0 +1,140 @@
+import { isStaffEmail } from "./staff.js";
+/**
+ * AI teammates (ADR 0032): Agents the whole workspace talks to, each person in
+ * one ongoing private chat per teammate, on the Copilot runtime.
+ *
+ * Staff-only on dev. `OXYGEN_TEAMMATES_ENABLED` is the switch; when it is
+ * unset the feature follows the Ongoing Agent sessions staff gate, which the
+ * dev web and worker already receive, because teammates re-scope those
+ * sessions into routines. Production and shadow never qualify.
+ */
+export function teammatesEnabled(env = process.env) {
+    if (env.OXYGEN_DEPLOY_ENV !== "selfhost-dev")
+        return false;
+    if (env.OXYGEN_AGENTS_ENABLED?.trim().toLowerCase() !== "true")
+        return false;
+    const flag = env.OXYGEN_TEAMMATES_ENABLED?.trim().toLowerCase();
+    if (flag)
+        return flag === "staff";
+    return env.OXYGEN_AGENT_SESSIONS_ENABLED === "staff";
+}
+export function teammatesAvailableTo(env, viewer) {
+    return teammatesEnabled(env) && viewer.member && viewer.oxygenRole !== "client" && isStaffEmail(viewer.email, env);
+}
+/**
+ * The Workspace Agent's slug. Every workspace's first Oxygent is that Agent: an
+ * Oxygent like the others, first in the list and where Home opens, with no role
+ * of its own (Tim, 2026-10-13: "The default agent should be Oxygent and not
+ * Chief of Staff").
+ */
+export const DEFAULT_TEAMMATE_SLUG = "workspace";
+/** What an Oxygent is called until someone names it, as Grok Bot's are (Tim, 2026-10-13). */
+export const NEW_TEAMMATE_NAME = "New Bot";
+const LEGACY_WORKSPACE_AGENT_NAME = "Workspace Agent";
+const LEGACY_WORKSPACE_AGENT_DESCRIPTION = "General organization-grounded workspace worker.";
+export const TEAMMATE_NAME_MAX_CHARS = 80;
+export const TEAMMATE_DESCRIPTION_MAX_CHARS = 500;
+/**
+ * An Oxygent's look, picked like a Grok Bot bot's (Tim, 2026-10-13): one of
+ * these shapes, each a little molecule of round atoms with eyes, in one of
+ * these colours. The web draws them; anything else stored reads as unset.
+ */
+export const TEAMMATE_AVATAR_KEYS = [
+    "o2", "atom", "twin", "tripod", "mark", "clover", "trio", "bubbles", "crown", "orbit", "comet", "pill",
+];
+export const TEAMMATE_AVATAR_COLORS = [
+    "forest", "brown", "red", "orange", "amber", "green", "aqua", "blue", "violet", "purple", "magenta", "slate",
+];
+export function isTeammateAvatarKey(value) {
+    return typeof value === "string" && TEAMMATE_AVATAR_KEYS.includes(value);
+}
+export function isTeammateAvatarColor(value) {
+    return typeof value === "string" && TEAMMATE_AVATAR_COLORS.includes(value);
+}
+/**
+ * The look an Oxygent wears until someone picks one: the first Oxygent wears
+ * OXYGEN's own (an O2 molecule in forest green); any other one a look its slug
+ * picks, so a new one never arrives looking like the last.
+ */
+export function teammateDefaultLook(slug) {
+    if (slug === DEFAULT_TEAMMATE_SLUG)
+        return { avatarKey: "o2", avatarColor: "forest" };
+    let hash = 2166136261;
+    for (const char of slug) {
+        hash ^= char.charCodeAt(0);
+        hash = Math.imul(hash, 16777619);
+    }
+    const unsigned = hash >>> 0;
+    return {
+        avatarKey: TEAMMATE_AVATAR_KEYS[unsigned % TEAMMATE_AVATAR_KEYS.length],
+        avatarColor: TEAMMATE_AVATAR_COLORS[(unsigned >>> 8) % TEAMMATE_AVATAR_COLORS.length],
+    };
+}
+/**
+ * How an Oxygent presents: its name, what it does and its look. The first
+ * Oxygent is "New Bot" until its owner names it; nothing renames the stored
+ * Agent to get there, and the Workspace Agent's stock description is no job.
+ */
+export function teammatePresentation(agent) {
+    const first = agent.slug === DEFAULT_TEAMMATE_SLUG;
+    const name = first && agent.name === LEGACY_WORKSPACE_AGENT_NAME ? NEW_TEAMMATE_NAME : agent.name;
+    const stored = agent.description?.trim() ?? "";
+    const description = first && stored === LEGACY_WORKSPACE_AGENT_DESCRIPTION ? "" : stored;
+    const look = teammateDefaultLook(agent.slug);
+    return {
+        name,
+        description,
+        avatarKey: isTeammateAvatarKey(agent.avatarKey) ? agent.avatarKey : look.avatarKey,
+        avatarColor: isTeammateAvatarColor(agent.avatarColor) ? agent.avatarColor : look.avatarColor,
+    };
+}
+/** How much of a teammate's latest words its roster row shows. */
+export const TEAMMATE_PREVIEW_MAX_CHARS = 140;
+/**
+ * One line of a teammate's latest words, for its roster row: the markdown
+ * reduced to its text, whitespace collapsed, cut at a word near `maxChars`.
+ */
+export function teammatePreviewLine(text, maxChars = TEAMMATE_PREVIEW_MAX_CHARS) {
+    const plain = text
+        .replace(/```[\s\S]*?(?:```|$)/g, " ")
+        .replace(/<!--[\s\S]*?-->/g, " ")
+        .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1")
+        .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+        .replace(/`([^`]*)`/g, "$1")
+        // A table's rule row or a horizontal rule carries no words.
+        .replace(/^[ \t]*[-:|* \t]{3,}$/gm, " ")
+        .replace(/^[ \t]{0,3}(?:#{1,6}|>|[-*+]|\d+[.)])[ \t]+/gm, "")
+        .replace(/(\*\*|__|~~)(?=\S)([\s\S]*?\S)\1/g, "$2")
+        .replace(/(^|[^\w*])([*_])(?=\S)([^*_\n]*?\S)\2(?![\w*])/g, "$1$3")
+        .replace(/\|/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (plain.length <= maxChars)
+        return plain;
+    const cut = plain.slice(0, maxChars);
+    // A cut that lands on a space already ends on a whole word.
+    const space = plain[maxChars] === " " ? maxChars : cut.lastIndexOf(" ");
+    const word = space > maxChars * 0.6 ? cut.slice(0, space) : cut;
+    return `${word.replace(/[\s,;:.\-–—]+$/, "")}…`;
+}
+/** A handle made from a teammate's name ("Lead Scout" → "lead-scout"); null when nothing usable is left. */
+export function teammateSlugFromName(name) {
+    const slug = name
+        .normalize("NFKD")
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^[^a-z]+/, "")
+        .slice(0, 40)
+        .replace(/-+$/, "");
+    return /^[a-z][a-z0-9-]{1,48}$/.test(slug) ? slug : null;
+}
+/**
+ * The first instructions of an Oxygent added from the sidebar or the CLI. They
+ * name no name and no job: the chat's role block says both from the profile,
+ * which its owner edits at any time, where a published version would go stale.
+ */
+export const TEAMMATE_STARTER_INSTRUCTIONS = [
+    "You are an Oxygent on the team. Do the job your profile and the person give you, and hand work that is another Oxygent's job to them.",
+    "Read whatever you need from the workspace; ask before anything that writes, sends or spends.",
+].join("\n");