A local-first multi-agent app development platform, built on PenguinHarness
import fs from "node:fs/promises";
import path from "node:path";
/**
* The organization service: what the routes (and through them the CLI and the Web App)
* call. Every write is a validated edit of an organization file under the organization's
* lock, followed by an immediate reconcile pass so the change takes effect now; every
* read is a projection of the files plus the live session state and the period's spend.
*/
import type {
OrgCalendarItem,
OrgCalendarResponse,
OrgCalendarUpsertRequest,
OrgCalendarWriteResponse,
SemanticIdSuggestRequest,
SemanticIdSuggestResponse,
OrgChannelCreateRequest,
OrgChannelDetail,
OrgChannelItem,
OrgChannelMember,
OrgChannelPatchRequest,
OrgChannelsResponse,
OrgChannelMessage,
OrgChannelMessageSendRequest,
OrgChannelMessagesResponse,
OrgChartResponse,
OrgDeskResponse,
OrgEmployeeItem,
OrgEmployeePatchRequest,
OrgFinanceResponse,
OrgHireRequest,
OrgInbox,
OrgSessionsResponse,
OrgTicketCreateRequest,
OrgTicketDetail,
OrgTicketHistoryAction,
OrgTicketItem,
OrgTicketSessionItem,
OrgTicketStatus,
OrgTicketUpdateRequest,
OrgTicketsResponse,
OrganizationCreateRequest,
OrganizationDetail,
OrganizationPatchRequest,
OrganizationSettings,
OrganizationSummary,
OrgLanguage,
ScheduleStatus,
OrgHandbookFileResponse,
OrgHandbookFilesResponse,
} from "../../api/types.js";
import { TICKET_SLUG_PATTERN } from "../../api/types.js";
import { Interface, Module, Provide, Use } from "@adelie/core/kernel";
import type { ClassCtx } from "@adelie/core/kernel";
import { HttpError } from "../../http/errors.js";
import { userChannelKey } from "../../http/routes/events.js";
import type { Channels, Clock, Config, Log } from "../../hmr/capabilities.js";
import type { ChannelHub } from "../channel.js";
import type { OrgCache } from "../../mechanisms/organization.js";
import type { AgentConfig, AgentLifecycle } from "../../mechanisms/agents.js";
import type {
AgentIndex,
Members,
ProjectConfigStore,
Projects,
} from "../../mechanisms/projects.js";
import type { MessagingBindings } from "../../mechanisms/messaging.js";
import type { SessionIndex } from "../../mechanisms/sessions.js";
import type { Settings } from "../../mechanisms/settings.js";
import type { Errors, UsageQueries } from "../../mechanisms/observability.js";
import { OrgStore } from "../../organization/store.js";
import { badRequest } from "../../http/validate.js";
import type { ChannelConfig, OrgConfig, OrgEmployee, TicketDoc } from "../../organization/files.js";
import {
BUDGET_RATIO_MAX,
DEFAULT_CEO_BUDGET,
MENTION_CHAIN_LIMIT_MAX,
ORG_CONFIG_DEFAULTS,
TICKET_ID_PATTERN,
defaultTicketNotify,
detectLanguage,
extractMentionTokens,
historyNote,
orgLanguage,
parseCalendarEvent,
parseOrgChart,
serializeCalendarEvent,
serializeOrgChart,
slugSuffix,
slugify,
} from "../../organization/files.js";
import { renderHandbook } from "../../organization/handbook.js";
import {
DEFAULT_CHANNEL_ID,
ORG_TICKET_COLUMNS,
ceoAgentId,
isChannelId,
isHandbookFilePath,
isTicketColumn,
normalizeWorkspaceSpec,
} from "../../organization/paths.js";
import {
agentPrincipal,
parsePrincipal,
principalAgentId,
userPrincipal,
} from "../../organization/principal.js";
import { isValidTimeZone, zonedDate, zonedDayRange } from "../../organization/zoned.js";
import { SEMANTIC_ID_RULES } from "../../services/semantic-id.js";
import { suggestSemanticId } from "../../services/semantic-id-suggest.js";
import { SEMANTIC_ID_PATTERN } from "../../services/ids.js";
import { enabledMessagingChannel } from "../messaging/enabled-channel.js";
import { latestSlotAt, nextSlotAfter, slotInWindow } from "../schedule-file.js";
import type { ScheduleDefinition } from "../schedule-file.js";
import { budgetLine, budgetRatio, computeSpend, pausedEmployees } from "./budget.js";
import type { OrgSpend } from "./budget.js";
import { DEFAULT_EMPLOYEE_PLUGINS, OrgRuns, OrgSessions, employeePlugins } from "./deps.js";
import type { OrgDeps } from "./deps.js";
import { loadOrg, sharedWorkspace } from "./model.js";
import type { LoadedOrg } from "./model.js";
import {
channelArchiveChanged,
channelCreated,
channelMemberAdded,
channelMemberRemoved,
employeeJoined,
employeeLeft,
systemMessage,
} from "./notices.js";
import { appendChannelMessage, listTickets, syncApprovalMode, syncCaches } from "./reconcile.js";
import type { LoadedTicket } from "./reconcile.js";
import { rotaWarnings } from "./rota.js";
import { OrganizationScheduler } from "./scheduler.js";
import { dispatchToDesk, ensureDesk, openTicketSession } from "./triggers.js";
/**
* The CEO's partition of the shared workspace. The root of the shared workspace holds the
* inputs every desk reads — specs, data, prior deliverables — and is nobody's desk, so the
* CEO gets a sub-directory of its own like every other employee.
*/
const CEO_WORKSPACE = "ceo";
/**
* Who performs a write: a person (route user) or, through the control-env token from the
* control environment of a session, that session's employee. `agentId` is the employee the
* command subprocess was handed (`ADELIE_AGENT_ID`) and it wins over the session, so a
* command run from a subagent or a nested session of an employee is still recorded as that
* employee; `sessionId` answers when there is no Agent id to go by.
*/
export interface Actor {
userId: string;
sessionId?: string;
agentId?: string;
}
const notFound = (orgId: string): HttpError =>
new HttpError(404, "org_not_found", `Organization does not exist: ${orgId}`);
const ticketNotFound = (ticketId: string): HttpError =>
new HttpError(404, "ticket_not_found", `Ticket does not exist: ${ticketId}`);
const channelNotFound = (channelId: string): HttpError =>
new HttpError(404, "channel_not_found", `Channel does not exist: ${channelId}`);
const channelArchived = (channelId: string): HttpError =>
new HttpError(
409,
"channel_archived",
`Channel ${channelId} is archived: unarchive it before writing to it.`,
);
const notAMember = (channelId: string, principal: string, why?: string): HttpError =>
new HttpError(
403,
"not_a_member",
why ?? `${principal} is not a member of the channel ${channelId}.`,
);
const allHandsImmutable = (message: string): HttpError =>
new HttpError(400, "all_hands_immutable", message);
/**
* The two numeric settings, held to the bounds the config parser enforces. The settings
* write path is the looser of the two, so a value it let through would be written and then
* refuse to parse on the next load — the organization is marked invalid and its automation
* stops. The bounds themselves live beside the parser; only the request wording is here.
*/
const requireChainLimit = (value: number): number => {
if (!Number.isInteger(value) || value < 0 || value > MENTION_CHAIN_LIMIT_MAX) {
throw badRequest(
`mentionChainLimit must be an integer between 0 and ${MENTION_CHAIN_LIMIT_MAX}.`,
);
}
return value;
};
const requireBudgetRatio = (key: string, value: number): number => {
if (!(value > 0) || value > BUDGET_RATIO_MAX)
throw badRequest(`${key} must be a number in (0, ${BUDGET_RATIO_MAX}].`);
return value;
};
export class OrganizationService {
constructor(
private readonly deps: OrgDeps,
private readonly scheduler: OrganizationScheduler,
) {}
private now(): number {
return this.deps.now?.() ?? Date.now();
}
/** The organization a session belongs to, for the `ADELIE_ORG_ID` control variable. */
orgIdOfSession(sessionId: string): string | null {
return this.deps.cache.ownerOfSession(sessionId)?.orgId ?? null;
}
/**
* A semantic id for a display name (the organization and channel dialogs name the thing
* first and derive the id): the shared proposal (semantic-id-suggest.ts) with the kind's
* prefix, the ids the dialog passed in to avoid, and every model dead end recorded as the
* organization's.
*/
async suggestId(
projectId: string,
req: SemanticIdSuggestRequest,
): Promise<SemanticIdSuggestResponse> {
return suggestSemanticId(
{
completeOnce: this.deps.completeOnce,
recordFailure: (p, detail) => this.recordIdSuggestFailure(p, detail),
},
projectId,
{
name: req.name,
kind: req.kind,
rule: SEMANTIC_ID_RULES[req.kind],
taken: req.taken ?? [],
},
);
}
/** One dead end of an id proposal, in the log and in the Project's errors panel. */
private recordIdSuggestFailure(projectId: string, message: string): void {
this.deps.log?.(`org: id suggestion fell back for ${projectId}: ${message}`);
this.deps.errors.record({
source: "organization",
code: "id_suggest_failed",
kind: "expected",
ctx: { projectId },
err: new Error(message),
});
}
private async requireOrg(projectId: string, orgId: string): Promise<LoadedOrg> {
const org = await loadOrg(this.deps, projectId, orgId);
if (org === null) throw notFound(orgId);
return org;
}
/** A write that needs the chart: an invalid organization is repaired by editing its files, not through the API. */
private async requireValidOrg(projectId: string, orgId: string): Promise<LoadedOrg> {
const org = await this.requireOrg(projectId, orgId);
if (org.invalid !== undefined) {
throw new HttpError(409, "org_invalid", `Organization ${orgId} needs repair: ${org.invalid}`);
}
return org;
}
/**
* The principal a write is recorded under: the Agent id the caller carries when it names an
* employee of this organization, else the employee of the calling session, else the person.
* The Agent id comes first because it is the narrower fact — the session may be a desk that
* spawned the command, while `ADELIE_AGENT_ID` names exactly who ran it.
*/
private actorPrincipal(org: LoadedOrg, actor: Actor): string {
if (actor.agentId !== undefined && org.byId.has(actor.agentId)) {
return agentPrincipal(actor.agentId);
}
if (actor.sessionId !== undefined) {
const owner = this.deps.cache.ownerOfSession(actor.sessionId);
if (owner && owner.projectId === org.projectId && owner.orgId === org.orgId) {
return agentPrincipal(owner.agentId);
}
const row = this.deps.sessions.findById(actor.sessionId);
if (row && row.projectId === org.projectId && org.byId.has(row.agentId))
return agentPrincipal(row.agentId);
}
return userPrincipal(actor.userId);
}
/**
* The employee an actor writes as, or null when it writes as a person. The one question
* the ticket-start rule asks: a desk or ticket session names its employee, everything else
* — the Web App, a signed-in CLI outside a session — is a person of the Project.
*/
private actorEmployee(org: LoadedOrg, actor: Actor): string | null {
return principalAgentId(this.actorPrincipal(org, actor));
}
// ---------------------------------------------------------------------------
// Organizations
// ---------------------------------------------------------------------------
async list(projectId: string): Promise<OrganizationSummary[]> {
const out: OrganizationSummary[] = [];
for (const orgId of await this.deps.store.listOrgIds(projectId)) {
const org = await loadOrg(this.deps, projectId, orgId);
if (org === null) continue;
const { tickets } = await listTickets(this.deps, org);
const spend = await computeSpend(this.deps, org, tickets);
out.push(this.summary(org, tickets, spend));
}
return out;
}
private summary(
org: LoadedOrg,
tickets: readonly LoadedTicket[],
spend: OrgSpend,
): OrganizationSummary {
const paused = pausedEmployees(this.deps, org, spend.period);
let running = 0;
for (const e of org.chart.employees) if (this.employeeRunning(org, e.agentId)) running++;
const ceo = ceoAgentId(org.orgId);
const ceoBudget = org.byId.get(ceo)?.budget;
const cost = spend.cumulative.get(ceo) ?? 0;
return {
projectId: org.projectId,
orgId: org.orgId,
name: org.config.name,
mission: org.config.mission,
status: org.config.status,
employeeCount: org.chart.employees.length,
runningCount: running,
pausedCount: paused.size,
openTickets: tickets.filter((t) => t.column !== "done" && t.column !== "rejected").length,
blockedTickets: tickets.filter((t) => t.doc.blocked !== undefined && t.doc.blocked !== "")
.length,
createdBy: org.config.createdBy,
spend: {
period: spend.period,
cost,
...(ceoBudget !== undefined
? { budget: ceoBudget, ratio: budgetRatio(cost, ceoBudget) }
: {}),
},
...(org.invalid !== undefined ? { invalid: org.invalid } : {}),
};
}
private employeeRunning(org: LoadedOrg, agentId: string): boolean {
const desk = org.desks[agentId];
if (desk && this.deps.runner.statusOf(desk.sessionId) !== "idle") return true;
for (const row of this.deps.cache.ticketSessions(org.projectId, org.orgId)) {
if (row.agentId === agentId && this.deps.runner.statusOf(row.sessionId) !== "idle")
return true;
}
return false;
}
private settings(org: LoadedOrg): OrganizationSettings {
return {
name: org.config.name,
mission: org.config.mission,
status: org.config.status,
timezone: org.config.timezone,
approvalMode: org.config.approvalMode,
mentionChainLimit: org.config.mentionChainLimit,
budgetWarnRatio: org.config.budgetWarnRatio,
budgetPauseRatio: org.config.budgetPauseRatio,
createdBy: org.config.createdBy,
// Always the effective language, never the raw field: an organization written before
// the field existed still has one, read from its mission.
language: orgLanguage(org.config),
...(org.config.workspace !== undefined ? { workspace: org.config.workspace } : {}),
...(org.config.model !== undefined ? { model: org.config.model } : {}),
};
}
/** A shared-workspace root chosen by the user: absolute and an existing directory. */
private async requireWorkspaceDir(spec: string): Promise<string> {
if (!path.isAbsolute(spec)) throw badRequest("workspace must be an absolute path.");
const real = await fs.stat(spec).then(
(s) => (s.isDirectory() ? spec : null),
() => null,
);
if (real === null) throw badRequest(`workspace directory does not exist: ${spec}`);
return real;
}
async detail(projectId: string, orgId: string, userId: string): Promise<OrganizationDetail> {
const org = await this.requireOrg(projectId, orgId);
const { tickets } = await listTickets(this.deps, org);
const spend = await computeSpend(this.deps, org, tickets);
const summary = this.summary(org, tickets, spend);
const board = Object.fromEntries(ORG_TICKET_COLUMNS.map((c) => [c, 0])) as Record<
OrgTicketStatus,
number
>;
for (const t of tickets) board[t.column]++;
const nowMs = this.now();
const todayDate = zonedDate(org.config.timezone, nowMs);
const day = zonedDayRange(org.config.timezone, todayDate);
const calendar = await this.calendarItems(org, spend);
const today = calendar.events.filter((e) => {
const inDay = (iso: string | undefined): boolean => {
if (iso === undefined) return false;
const ms = Date.parse(iso);
return ms >= day.fromMs && ms < day.toMs;
};
return inDay(e.nextFireAt) || inDay(e.lastFiredAt);
});
// The overview opens even when the all-hands channel's file is missing or unreadable (a
// hand edit): it then reports no recent messages instead of refusing the page.
const allHands = await this.deps.store.readChannel(org.dir, DEFAULT_CHANNEL_ID);
const recent =
allHands?.parsed.ok === true
? await this.channelMessages(projectId, orgId, { userId }, DEFAULT_CHANNEL_ID, {})
: null;
const mentions = await this.pendingMentions(org, userId);
const me = userPrincipal(userId);
const items = this.ticketItems(tickets, spend);
const ceoDesk = org.desks[ceoAgentId(orgId)];
return {
...summary,
settings: this.settings(org),
board,
today,
pending: {
mentions,
reviewTickets: items.filter((t) => t.status === "review"),
blockedByMe: items.filter((t) => t.blockedBy === me),
},
recentMessages: recent?.messages.slice(-20) ?? [],
inbox: this.inbox(spend, items, tickets, recent?.messages ?? [], me),
alerts: this.alerts(org, spend.period),
...(ceoDesk !== undefined ? { ceoDeskSessionId: ceoDesk.sessionId } : {}),
};
}
/**
* The overview's inbox — what a person is waited on or told about, read from the same
* files `detail` already loaded:
*
* - `mentions`: the all-hands messages of the window `recentMessages` reads (the
* organization's current day) that name the caller or `all`, newest first.
* - `blockedTickets`: every ticket carrying a `blocked` reason, whoever it waits on —
* uncapped, because a blocked ticket is work nobody is doing.
* - `doneTickets`: tickets in `done` that closed in the current budget period, `closedAt`
* taken from the last `moved`-to-`done` history entry. A ticket whose file was moved by
* hand has no such entry and no closing time to test, so it is listed with `closedAt`
* absent rather than hidden.
*
* Newest first everywhere; ticket ids start with the filing date, so ordering by id
* descending is ordering by age.
*/
private inbox(
spend: OrgSpend,
items: readonly OrgTicketItem[],
tickets: readonly LoadedTicket[],
windowMessages: readonly OrgChannelMessage[],
me: string,
): OrgInbox {
const mentions = windowMessages
.filter((m) => m.mentions.includes(me) || m.mentions.includes("all"))
.reverse()
.slice(0, INBOX_PAGE);
const newestFirst = <T extends { ticketId: string }>(a: T, b: T): number =>
a.ticketId < b.ticketId ? 1 : a.ticketId > b.ticketId ? -1 : 0;
const closedAt = new Map<string, string>();
for (const t of tickets) {
const at = lastClosedAt(t.doc);
if (at !== null) closedAt.set(t.ticketId, at);
}
const inPeriod = (iso: string): boolean => {
const ms = Date.parse(iso);
// An unparsable stamp is a hand-edited line, not evidence the ticket closed elsewhen.
return Number.isNaN(ms) || (ms >= spend.range.fromMs && ms < spend.range.toMs);
};
const doneTickets = items
.filter((t) => t.status === "done")
.map((t): OrgInbox["doneTickets"][number] => {
const at = closedAt.get(t.ticketId);
return { ...t, ...(at !== undefined ? { closedAt: at } : {}) };
})
.filter((t) => t.closedAt === undefined || inPeriod(t.closedAt))
.sort(newestFirst)
.slice(0, INBOX_PAGE);
return {
mentions,
blockedTickets: items.filter((t) => (t.blocked ?? "") !== "").sort(newestFirst),
doneTickets,
};
}
/** Mentions waiting for a person, summed over every channel they belong to. */
private async pendingMentions(org: LoadedOrg, userId: string): Promise<number> {
const me = userPrincipal(userId);
let mentions = 0;
for (const file of await this.deps.store.listChannels(org.dir)) {
if (!file.parsed.ok) continue;
if (!this.channelMemberPrincipals(org, file.parsed.value).includes(me)) continue;
mentions += (await this.channelActivity(org, file.channelId, userId)).mentionsMe;
}
return mentions;
}
private alerts(org: LoadedOrg, period: string): OrganizationDetail["alerts"] {
return this.deps.cache
.listBudgetStates(org.projectId, org.orgId, period)
.filter((s) => s.warnedAt !== null || s.pausedAt !== null)
.map((s) => ({
agentId: s.agentId,
period: s.period,
...(s.warnedAt !== null ? { warnedAt: s.warnedAt } : {}),
...(s.pausedAt !== null ? { pausedAt: s.pausedAt } : {}),
}));
}
/**
* Creates an organization as one whole: directory and files, the CEO Agent (with the
* company and orchestration plugins and an employee brief), then the initialization work
* run on the CEO's desk. Any failure removes what was written; a taken CEO id is a 409
* before anything is touched.
*/
async create(
projectId: string,
req: OrganizationCreateRequest,
userId: string,
): Promise<OrganizationDetail> {
const orgId = req.orgId;
if (!SEMANTIC_ID_PATTERN.test(orgId)) {
throw new HttpError(
400,
"invalid_org_id",
"Organization id must be 2–64 characters: a lowercase letter, then lowercase letters, digits or underscores.",
);
}
const mission = req.mission.trim();
if (mission === "") throw badRequest("mission must not be empty.");
const timezone = req.timezone ?? Intl.DateTimeFormat().resolvedOptions().timeZone ?? "UTC";
if (!isValidTimeZone(timezone)) throw badRequest(`Unknown timezone: ${timezone}`);
if (await this.deps.store.exists(projectId, orgId)) {
throw new HttpError(409, "org_exists", `Organization id is already taken: ${orgId}`);
}
const ceo = ceoAgentId(orgId);
if (await this.deps.agents.exists(projectId, ceo)) {
throw new HttpError(409, "agent_exists", `The CEO's Agent id is already taken: ${ceo}`);
}
const name = req.name?.trim() || orgId;
if (req.model !== undefined) await this.validateModel(projectId, req.model);
const workspace =
req.workspace !== undefined ? await this.requireWorkspaceDir(req.workspace) : undefined;
// The mission decides the working language unless the request names one: a company given
// a Chinese mission writes in Chinese, without anyone having to ask for it.
const language = req.language ?? detectLanguage(mission);
const config: OrgConfig = {
name,
mission,
status: "active",
timezone,
language,
approvalMode: ORG_CONFIG_DEFAULTS.approvalMode,
mentionChainLimit: ORG_CONFIG_DEFAULTS.mentionChainLimit,
budgetWarnRatio: ORG_CONFIG_DEFAULTS.budgetWarnRatio,
budgetPauseRatio: ORG_CONFIG_DEFAULTS.budgetPauseRatio,
createdBy: userId,
...(workspace !== undefined ? { workspace } : {}),
...(req.model !== undefined ? { model: req.model } : {}),
};
const dir = this.deps.store.dir(projectId, orgId);
// The layout is written under the organization's lock — the same one a delete holds when
// it moves the directory to the trash. Unlocked, a delete landing between the exists
// check above and the lock below would move the half-made directory away and leave this
// method writing chart and handbook beside a config that is no longer there.
await this.scheduler.withLock(projectId, orgId, async () => {
await this.deps.store.createLayout(dir, new Date(this.now()).toISOString());
try {
await this.deps.store.writeConfig(dir, config);
await this.deps.store.writeChart(dir, {
employees: [
{
agentId: ceo,
title: "CEO",
reportsTo: null,
duties:
language === "zh"
? "把使命拆成工单、招募、划分公共工作区、审核工单、向董事会汇报"
: "Turn the mission into tickets, hire, partition the shared workspace, review tickets, report to the board",
workspace: CEO_WORKSPACE,
// Compared on the cumulative line, so this one number is the whole company's cap.
budget: req.ceoBudget ?? DEFAULT_CEO_BUDGET,
},
],
});
await this.deps.store.writeHandbook(
dir,
renderHandbook({ orgId, name, mission, ceoAgentId: ceo, createdBy: userId, language }),
);
await this.deps.agents.create(
projectId,
ceo,
`${name} CEO`,
`CEO of ${name}`,
DEFAULT_EMPLOYEE_PLUGINS,
);
await this.deps.agents.writeAgentsMd(
projectId,
ceo,
employeeBrief({
orgId,
name,
mission,
agentId: ceo,
title: "CEO",
reportsTo: null,
language,
}),
);
} catch (err) {
await this.deps.store.remove(dir);
throw err;
}
});
await this.scheduler.withLock(projectId, orgId, async () => {
const org = await this.requireValidOrg(projectId, orgId);
const spend = await computeSpend(this.deps, org, []);
await dispatchToDesk(this.deps, org, ceo, { kind: "init" }, initBody(org), {
hop: 0,
budget: budgetLine(org, spend, ceo),
});
});
await this.scheduler.reconcile(projectId, orgId);
return this.detail(projectId, orgId, userId);
}
/**
* Deletes the organization — and ONLY the organization: its directory goes to the Project's
* trash (store.trash), whole and restorable, and the rows this server derived from it go
* with it, since a new organization under the same id must not inherit
* another's read cursors, calendar state or pending notices.
*
* What it had is left exactly as it is. Its employees stay Agents of the Project, with
* everything they learned. Its desk and ticket Sessions stay too, still marked as an
* organization's (`client = org`), so they do not spill into development mode's list;
* with the organization gone no page lists them either, which is the price of not
* deleting conversations along with a company.
*
* Under the organization's lock, so a pass in flight finishes first and the next one finds
* no directory — the same state a hand-removed directory always was.
*/
async delete(projectId: string, orgId: string): Promise<void> {
await this.requireOrg(projectId, orgId);
await this.scheduler.withLock(projectId, orgId, async () => {
await this.deps.store.trash(projectId, orgId, new Date(this.now()).toISOString());
this.deps.cache.deleteOrg(projectId, orgId);
});
this.deps.log?.(`[organization] ${projectId}/${orgId} deleted (moved to the trash)`);
}
async patch(
projectId: string,
orgId: string,
req: OrganizationPatchRequest,
userId: string,
): Promise<OrganizationSettings> {
return this.scheduler.withLock(projectId, orgId, async () => {
const org = await this.requireOrg(projectId, orgId);
// A broken config is rewritten whole from the request over the defaults loadOrg filled in.
const next: OrgConfig = { ...org.config };
// `created_by` is the one default that does not parse: a config that failed to load
// carries it empty, and writing that back would leave the file just as unreadable, so
// the repair this route exists for would return 200 and change nothing. Whoever is
// fixing it becomes its creator; a config that loaded keeps the creator it names.
if (next.createdBy === "") next.createdBy = userId;
if (req.name !== undefined) {
if (req.name.trim() === "") throw badRequest("name must not be empty.");
next.name = req.name.trim();
}
if (req.mission !== undefined) next.mission = req.mission.trim();
if (req.status !== undefined) next.status = req.status;
if (req.approvalMode !== undefined) next.approvalMode = req.approvalMode;
if (req.timezone !== undefined) {
if (!isValidTimeZone(req.timezone)) throw badRequest(`Unknown timezone: ${req.timezone}`);
next.timezone = req.timezone;
}
if (req.language !== undefined) next.language = req.language;
if (req.mentionChainLimit !== undefined)
next.mentionChainLimit = requireChainLimit(req.mentionChainLimit);
if (req.budgetWarnRatio !== undefined)
next.budgetWarnRatio = requireBudgetRatio("budgetWarnRatio", req.budgetWarnRatio);
if (req.budgetPauseRatio !== undefined)
next.budgetPauseRatio = requireBudgetRatio("budgetPauseRatio", req.budgetPauseRatio);
if (req.workspace === null) delete next.workspace;
else if (req.workspace !== undefined)
next.workspace = await this.requireWorkspaceDir(req.workspace);
if (req.model === null) delete next.model;
else if (req.model !== undefined) {
await this.validateModel(projectId, req.model);
next.model = req.model;
}
const modeChanged = next.approvalMode !== org.config.approvalMode;
await this.deps.store.writeConfig(org.dir, next);
org.config = next;
// Every API write of the approval mode comes through here, so this is where a change
// reaches the desk and ticket sessions already open rather than only the next ones. A
// hand edit of org_config.toml does not pass here.
if (modeChanged) {
const { tickets } = await listTickets(this.deps, org);
syncApprovalMode(this.deps, org, tickets);
}
return this.settings(org);
});
}
// ---------------------------------------------------------------------------
// Employees, desks, handbook
// ---------------------------------------------------------------------------
async chart(projectId: string, orgId: string): Promise<OrgChartResponse> {
const org = await this.requireOrg(projectId, orgId);
const { tickets } = await listTickets(this.deps, org);
const spend = await computeSpend(this.deps, org, tickets);
return { ceoAgentId: ceoAgentId(orgId), employees: await this.employeeItems(org, spend) };
}
private async employeeItems(org: LoadedOrg, spend: OrgSpend): Promise<OrgEmployeeItem[]> {
const paused = pausedEmployees(this.deps, org, spend.period);
const out: OrgEmployeeItem[] = [];
const shared = sharedWorkspace(org);
for (const e of org.chart.employees) {
const exists = await this.deps.agents.exists(org.projectId, e.agentId);
// A relative sub-directory that is not there yet is not a broken entry: it is created
// when the employee is first put to work. Only a spec that leaves the shared workspace,
// or an absolute directory nobody created, makes the entry unusable.
const workspace = this.deps.store.workspaceTarget(shared, e.workspace);
const absentAbsolute =
workspace !== null &&
path.isAbsolute(e.workspace) &&
(await this.deps.store.resolveWorkspace(shared, e.workspace)) === null;
const invalid = !exists
? `Agent ${e.agentId} does not exist`
: workspace === null
? `workspace leaves the shared workspace: ${e.workspace}`
: absentAbsolute
? `workspace directory does not exist: ${e.workspace}`
: undefined;
const own = spend.own.get(e.agentId) ?? 0;
const cumulative = spend.cumulative.get(e.agentId) ?? 0;
const desk = org.desks[e.agentId];
out.push({
agentId: e.agentId,
name: exists ? await this.deps.agents.displayName(org.projectId, e.agentId) : e.agentId,
title: e.title,
reportsTo: e.reportsTo,
...(e.duties !== undefined ? { duties: e.duties } : {}),
workspace: e.workspace,
...(workspace !== null ? { resolvedWorkspace: workspace } : {}),
...(e.budget !== undefined ? { budget: e.budget } : {}),
...(e.model !== undefined ? { model: e.model } : {}),
state: paused.has(e.agentId)
? "paused"
: this.employeeRunning(org, e.agentId)
? "running"
: "idle",
...(desk !== undefined
? {
desk: {
sessionId: desk.sessionId,
workspace: desk.workspace,
openedAt: desk.openedAt,
},
}
: {}),
spend: {
own,
cumulative,
...(e.budget !== undefined ? { ratio: budgetRatio(cumulative, e.budget) } : {}),
},
...(invalid !== undefined ? { invalid } : {}),
});
}
return out;
}
private async validateModel(
projectId: string,
model: { provider: string; modelId: string },
): Promise<void> {
const cfg = await this.deps.projectConfig.loadConfig(projectId);
const known = cfg.models.some(
(m) => m.provider === model.provider && m.model_id === model.modelId,
);
if (!known)
throw badRequest(
`Model (${model.provider}, ${model.modelId}) is not configured in this Project.`,
);
}
/**
* The workspace spec to store for an employee, with its directory ready: `./hr`, `hr/` and
* `hr` all become `hr`, a relative partition is created under the shared workspace, and an
* absolute path must already exist because it is a directory of the user's, not ours to
* make. A spec that climbs out of the shared workspace is refused outright. The spec is
* always the caller's: each entry point names its own default rather than falling back here.
*/
private async requireEmployeeWorkspace(org: LoadedOrg, spec: string): Promise<string> {
const normalized = normalizeWorkspaceSpec(spec);
const shared = sharedWorkspace(org);
if (this.deps.store.workspaceTarget(shared, normalized) === null) {
throw new HttpError(
400,
"invalid_workspace",
`workspace must stay inside the shared workspace: ${normalized}`,
);
}
if ((await this.deps.store.ensureWorkspace(shared, normalized)) === null) {
throw new HttpError(
400,
"invalid_workspace",
`workspace directory does not exist: ${normalized}`,
);
}
return normalized;
}
/** Writes a chart after re-validating it through the parser: the API never persists what a hand edit would be refused for. */
private async writeChart(org: LoadedOrg, employees: OrgEmployee[]): Promise<void> {
const raw = serializeOrgChart({ employees });
const parsed = parseOrgChart(raw, org.orgId);
if (!parsed.ok) throw badRequest(`Invalid employee tree: ${parsed.error}`);
await this.deps.store.writeChart(org.dir, parsed.value);
org.chart = parsed.value;
org.byId = new Map(parsed.value.employees.map((e) => [e.agentId, e]));
}
async hire(projectId: string, orgId: string, req: OrgHireRequest): Promise<OrgEmployeeItem> {
const item = await this.scheduler.withLock(projectId, orgId, async () => {
const org = await this.requireValidOrg(projectId, orgId);
const title = req.title.trim();
if (title === "") throw badRequest("title must not be empty.");
if (!org.byId.has(req.reportsTo))
throw badRequest(`reportsTo names no employee: ${req.reportsTo}`);
if ((req.agentId === undefined) === (req.newAgent === undefined)) {
throw badRequest(
"Give exactly one of agentId (an existing Agent) or newAgent (create one).",
);
}
if (req.model !== undefined) await this.validateModel(projectId, req.model);
const agentId = req.newAgent?.agentId ?? req.agentId!;
if (req.newAgent !== undefined) {
if (!SEMANTIC_ID_PATTERN.test(agentId))
throw badRequest("newAgent.agentId is not a valid Agent id.");
} else if (!(await this.deps.agents.exists(projectId, agentId))) {
throw new HttpError(404, "agent_not_found", `Agent does not exist: ${agentId}`);
}
if (org.byId.has(agentId))
throw new HttpError(409, "employee_exists", `${agentId} is already an employee.`);
// Before the Agent and the chart entry: the partition an employee is hired into exists
// from the moment the employee does, and a spec that leaves the shared workspace is
// refused rather than written and found broken on the first trigger. Omitted, it is a
// sub-directory named after the employee — the shared root is nobody's desk.
const workspace = await this.requireEmployeeWorkspace(org, req.workspace ?? agentId);
if (req.newAgent !== undefined) {
await this.deps.agents.create(
projectId,
agentId,
req.newAgent.name,
req.newAgent.description,
employeePlugins(req.newAgent.plugins),
);
await this.deps.agents.writeAgentsMd(
projectId,
agentId,
employeeBrief({
orgId,
name: org.config.name,
mission: org.config.mission,
agentId,
title,
reportsTo: req.reportsTo,
language: orgLanguage(org.config),
...(req.duties !== undefined ? { duties: req.duties } : {}),
}),
);
}
const employee: OrgEmployee = {
agentId,
title,
reportsTo: req.reportsTo,
...(req.duties !== undefined && req.duties.trim() !== ""
? { duties: req.duties.trim() }
: {}),
workspace,
...(req.budget !== undefined ? { budget: req.budget } : {}),
...(req.model !== undefined ? { model: req.model } : {}),
};
await this.writeChart(org, [...org.chart.employees, employee]);
await appendChannelMessage(
this.deps,
org,
DEFAULT_CHANNEL_ID,
systemMessage(
employeeJoined(agentPrincipal(agentId), title, agentPrincipal(req.reportsTo)),
),
);
// The desk exists from the moment the employee does. It is what every surface
// addressing the employee by Session id needs — the sidebar's desk row and its
// messaging binding, `penguin org desk show`, an @-mention — and opening it only on
// first use left a fresh hire with a row pointing at no Session at all. A desk is a
// Session, not a run: nothing is dispatched here. A failure (the Agent or the
// partition disappeared between the writes above and this line) is recorded and the
// hire still stands; the reconcile pass provisions the desk on its next sweep.
const desk = await ensureDesk(this.deps, org, agentId);
if (!desk.ok) {
this.deps.errors.record({
source: "organization",
err: new Error(desk.error),
code: "org_desk_unavailable",
ctx: { projectId, agentId },
});
}
const spend = await computeSpend(this.deps, org, (await listTickets(this.deps, org)).tickets);
const items = await this.employeeItems(org, spend);
return items.find((i) => i.agentId === agentId)!;
});
await this.scheduler.reconcile(projectId, orgId);
return item;
}
async patchEmployee(
projectId: string,
orgId: string,
agentId: string,
req: OrgEmployeePatchRequest,
): Promise<OrgEmployeeItem> {
const item = await this.scheduler.withLock(projectId, orgId, async () => {
const org = await this.requireValidOrg(projectId, orgId);
const current = org.byId.get(agentId);
if (!current)
throw new HttpError(404, "employee_not_found", `${agentId} is not an employee.`);
if (req.model !== undefined && req.model !== null)
await this.validateModel(projectId, req.model);
if (req.reportsTo !== undefined && current.reportsTo === null) {
throw badRequest("The CEO reports to nobody.");
}
const next: OrgEmployee = {
...current,
...(req.title !== undefined ? { title: req.title.trim() } : {}),
...(req.reportsTo !== undefined ? { reportsTo: req.reportsTo } : {}),
// A reassigned partition is created here, so the desk the next reconcile renews has
// its directory waiting for it.
...(req.workspace !== undefined
? { workspace: await this.requireEmployeeWorkspace(org, req.workspace) }
: {}),
...(req.duties !== undefined ? { duties: req.duties.trim() } : {}),
};
if (req.budget === null) delete next.budget;
else if (req.budget !== undefined) next.budget = req.budget;
if (req.model === null) delete next.model;
else if (req.model !== undefined) next.model = req.model;
if (next.duties === "") delete next.duties;
if (next.title === "") throw badRequest("title must not be empty.");
await this.writeChart(
org,
org.chart.employees.map((e) => (e.agentId === agentId ? next : e)),
);
const spend = await computeSpend(this.deps, org, (await listTickets(this.deps, org)).tickets);
const items = await this.employeeItems(org, spend);
return items.find((i) => i.agentId === agentId)!;
});
await this.scheduler.reconcile(projectId, orgId);
return item;
}
/**
* A Session's model moved (an in-session switch). When that Session is an employee's
* CURRENT desk the switch is the employee's: its chart entry takes the desk's model, so a
* desk renewed later opens on it (ticket Sessions read the desk itself, see
* `openTicketSession`). Any other Session — a ticket Session, a desk already replaced, one
* no organization owns — leaves the chart alone.
*/
async deskModelChanged(
sessionId: string,
model: { provider: string; modelId: string },
): Promise<void> {
const owner = this.deps.cache.ownerOfSession(sessionId);
if (owner === null || owner.kind !== "desk") return;
const { projectId, orgId, agentId } = owner;
await this.scheduler.withLock(projectId, orgId, async () => {
const org = await loadOrg(this.deps, projectId, orgId);
// An organization that needs repair is repaired by editing its files, not from here.
if (org === null || org.invalid !== undefined) return;
if (org.desks[agentId]?.sessionId !== sessionId) return;
const employee = org.byId.get(agentId);
if (!employee) return;
if (employee.model?.provider === model.provider && employee.model.modelId === model.modelId)
return;
await this.writeChart(
org,
org.chart.employees.map((e) => (e.agentId === agentId ? { ...e, model } : e)),
);
});
}
/** Removes the employee from the tree (subordinates move up to its manager); the Agent and its sessions stay. */
async leave(projectId: string, orgId: string, agentId: string): Promise<void> {
await this.scheduler.withLock(projectId, orgId, async () => {
const org = await this.requireValidOrg(projectId, orgId);
const current = org.byId.get(agentId);
if (!current)
throw new HttpError(404, "employee_not_found", `${agentId} is not an employee.`);
if (current.reportsTo === null) throw badRequest("The CEO cannot leave the organization.");
const manager = current.reportsTo;
await this.writeChart(
org,
org.chart.employees
.filter((e) => e.agentId !== agentId)
.map((e) => (e.reportsTo === agentId ? { ...e, reportsTo: manager } : e)),
);
if (org.desks[agentId] !== undefined) {
delete org.desks[agentId];
await this.deps.store.writeDesks(org.dir, org.desks);
}
// Nothing will sweep for this employee again, so its queued ticket changes and its
// waiting mentions go with it.
this.deps.cache.deleteDeskNotices(projectId, orgId, agentId);
this.deps.cache.deleteDeskMentions(projectId, orgId, agentId);
for (const f of await this.deps.store.listCalendar(org.dir)) {
if (f.agentId === agentId)
await this.deps.store.deleteCalendarEvent(org.dir, agentId, f.name);
}
// A departed employee is nobody's channel member any more: the files say who is in a
// channel, and a principal that is no longer an employee would be counted and listed.
for (const file of await this.deps.store.listChannels(org.dir)) {
if (!file.parsed.ok || file.parsed.value.everyone === true) continue;
const members = file.parsed.value.members ?? [];
if (!members.includes(agentPrincipal(agentId))) continue;
await this.deps.store.writeChannel(org.dir, file.channelId, {
...file.parsed.value,
members: members.filter((m) => m !== agentPrincipal(agentId)),
});
}
await appendChannelMessage(
this.deps,
org,
DEFAULT_CHANNEL_ID,
systemMessage(employeeLeft(agentPrincipal(agentId), agentPrincipal(manager))),
);
});
await this.scheduler.reconcile(projectId, orgId);
}
async desk(
projectId: string,
orgId: string,
agentId: string,
opts: { renew?: boolean },
): Promise<OrgDeskResponse> {
return this.scheduler.withLock(projectId, orgId, async () => {
const org = await this.requireValidOrg(projectId, orgId);
if (!org.byId.has(agentId))
throw new HttpError(404, "employee_not_found", `${agentId} is not an employee.`);
const r = await ensureDesk(this.deps, org, agentId, opts);
if (!r.ok) throw new HttpError(409, "desk_unavailable", r.error);
return { agentId, ...r.desk };
});
}
async handbook(projectId: string, orgId: string): Promise<string> {
const org = await this.requireOrg(projectId, orgId);
return this.deps.store.readHandbook(org.dir);
}
async writeHandbook(projectId: string, orgId: string, content: string): Promise<void> {
const org = await this.requireOrg(projectId, orgId);
await this.deps.store.writeHandbook(org.dir, content);
}
/** The handbook directory is the company's knowledge base; the index is listed first. */
async handbookFiles(projectId: string, orgId: string): Promise<OrgHandbookFilesResponse> {
const org = await this.requireOrg(projectId, orgId);
const files = await this.deps.store.listHandbookFiles(org.dir);
return {
files: files.map((f) => ({
path: f.path,
size: f.size,
updatedAt: new Date(f.mtimeMs).toISOString(),
})),
};
}
async handbookFile(
projectId: string,
orgId: string,
rel: string,
): Promise<OrgHandbookFileResponse> {
requireHandbookPath(rel);
const org = await this.requireOrg(projectId, orgId);
const content = await this.deps.store.readHandbookFile(org.dir, rel);
if (content === null)
throw new HttpError(404, "handbook_file_not_found", `${rel} is not in the handbook.`);
return { path: rel, content };
}
async writeHandbookFile(
projectId: string,
orgId: string,
rel: string,
content: string,
): Promise<OrgHandbookFileResponse> {
requireHandbookPath(rel);
const org = await this.requireOrg(projectId, orgId);
await this.deps.store.writeHandbookFile(org.dir, rel, content);
return { path: rel, content };
}
/** The index stays: it is what every trigger tells the employee to read. */
async deleteHandbookFile(projectId: string, orgId: string, rel: string): Promise<void> {
requireHandbookPath(rel);
if (rel === "README.md")
throw new HttpError(
400,
"handbook_index_required",
"The handbook index (README.md) cannot be deleted.",
);
const org = await this.requireOrg(projectId, orgId);
if ((await this.deps.store.readHandbookFile(org.dir, rel)) === null)
throw new HttpError(404, "handbook_file_not_found", `${rel} is not in the handbook.`);
await this.deps.store.deleteHandbookFile(org.dir, rel);
}
// ---------------------------------------------------------------------------
// Calendar
// ---------------------------------------------------------------------------
private async calendarItems(org: LoadedOrg, spend: OrgSpend): Promise<OrgCalendarResponse> {
const files = await this.deps.store.listCalendar(org.dir);
const paused = pausedEmployees(this.deps, org, spend.period);
const nowMs = this.now();
const events: OrgCalendarItem[] = [];
const invalidFiles: OrgCalendarResponse["invalidFiles"] = [];
for (const f of files) {
if (!f.parsed.ok) {
invalidFiles.push({ agentId: f.agentId, name: f.name, error: f.parsed.error });
continue;
}
if (!org.byId.has(f.agentId)) {
invalidFiles.push({ agentId: f.agentId, name: f.name, error: "belongs to no employee" });
continue;
}
const state = this.deps.cache.findCalendar(org.projectId, org.orgId, f.agentId, f.name);
const def = f.parsed.value;
const held = org.config.status === "paused" || paused.has(f.agentId);
const next = calendarNextFireAt(def, state, nowMs);
events.push({
agentId: f.agentId,
name: f.name,
...(def.title !== undefined ? { title: def.title } : {}),
prompt: def.prompt,
enabled: def.enabled,
startAt: def.startAt,
...(def.period !== undefined ? { period: def.period } : {}),
...(def.endAt !== undefined ? { endAt: def.endAt } : {}),
status: calendarStatus(def, state, nowMs),
...(state?.invalidReason ? { invalidReason: state.invalidReason } : {}),
...(next !== undefined ? { nextFireAt: next } : {}),
...(state?.lastFiredAt ? { lastFiredAt: state.lastFiredAt } : {}),
...(state?.lastOutcome ? { lastOutcome: state.lastOutcome } : {}),
paused: held,
});
}
return { events, invalidFiles };
}
async calendar(projectId: string, orgId: string): Promise<OrgCalendarResponse> {
const org = await this.requireOrg(projectId, orgId);
const { tickets } = await listTickets(this.deps, org);
const spend = await computeSpend(this.deps, org, tickets);
return this.calendarItems(org, spend);
}
async upsertCalendar(
projectId: string,
orgId: string,
agentId: string,
name: string,
fields: Omit<OrgCalendarUpsertRequest, "agentId" | "name">,
opts: { create: boolean },
): Promise<OrgCalendarWriteResponse> {
await this.scheduler.withLock(projectId, orgId, async () => {
const org = await this.requireValidOrg(projectId, orgId);
if (!org.byId.has(agentId))
throw new HttpError(404, "employee_not_found", `${agentId} is not an employee.`);
const existing = await this.deps.store.readCalendarEvent(org.dir, agentId, name);
if (opts.create && existing !== null) {
throw new HttpError(
409,
"calendar_event_exists",
`Calendar event already exists: ${agentId}/${name}`,
);
}
if (!opts.create && existing === null) {
throw new HttpError(
404,
"calendar_event_not_found",
`Calendar event does not exist: ${agentId}/${name}`,
);
}
const raw = serializeCalendarEvent({
...(fields.title !== undefined ? { title: fields.title } : {}),
prompt: fields.prompt,
enabled: fields.enabled,
startAt: fields.startAt,
...(fields.period !== undefined ? { period: fields.period } : {}),
...(fields.endAt !== undefined ? { endAt: fields.endAt } : {}),
});
const parsed = parseCalendarEvent(name, raw);
if (!parsed.ok) throw badRequest(`Invalid calendar event: ${parsed.error}`);
await this.deps.store.writeCalendarEvent(org.dir, agentId, name, raw);
});
await this.scheduler.reconcile(projectId, orgId);
const org = await this.requireOrg(projectId, orgId);
const spend = await computeSpend(this.deps, org, (await listTickets(this.deps, org)).tickets);
const list = await this.calendarItems(org, spend);
const item = list.events.find((e) => e.agentId === agentId && e.name === name);
if (!item)
throw new HttpError(
404,
"calendar_event_not_found",
`Calendar event does not exist: ${agentId}/${name}`,
);
// Advisory, computed over the whole calendar after the write: the rota is a property of
// the organization, not of the one event, and the write is never refused for it.
const warnings = rotaWarnings(list.events, item, this.now(), org.config.timezone);
return { ...item, ...(warnings.length > 0 ? { warnings } : {}) };
}
async deleteCalendar(
projectId: string,
orgId: string,
agentId: string,
name: string,
): Promise<void> {
await this.scheduler.withLock(projectId, orgId, async () => {
const org = await this.requireOrg(projectId, orgId);
const removed = await this.deps.store.deleteCalendarEvent(org.dir, agentId, name);
if (!removed)
throw new HttpError(
404,
"calendar_event_not_found",
`Calendar event does not exist: ${agentId}/${name}`,
);
this.deps.cache.deleteCalendar(projectId, orgId, agentId, name);
});
}
// ---------------------------------------------------------------------------
// Tickets
// ---------------------------------------------------------------------------
/** `known` is every ticket id in the same listing: a `parent` naming none is flagged invalid. */
private ticketItem(t: LoadedTicket, spend: OrgSpend, known: ReadonlySet<string>): OrgTicketItem {
const d = t.doc;
const running = d.sessions.some((s) => this.deps.runner.statusOf(s) !== "idle");
return {
ticketId: t.ticketId,
title: d.title,
status: d.status,
owner: d.owner,
...(d.parent !== undefined ? { parent: d.parent } : {}),
notify: d.notify,
priority: d.priority,
...(d.due !== undefined ? { due: d.due } : {}),
...(d.blocked !== undefined && d.blocked !== "" ? { blocked: d.blocked } : {}),
...(d.blockedBy !== undefined && d.blockedBy !== "" ? { blockedBy: d.blockedBy } : {}),
sessions: d.sessions,
running,
cost: spend.ticket.get(t.ticketId) ?? 0,
...(d.parent !== undefined && !known.has(d.parent)
? { invalid: `Parent ${d.parent} does not exist` }
: {}),
};
}
private ticketItems(tickets: readonly LoadedTicket[], spend: OrgSpend): OrgTicketItem[] {
const known = new Set(tickets.map((t) => t.ticketId));
return tickets.map((t) => this.ticketItem(t, spend, known));
}
async tickets(projectId: string, orgId: string): Promise<OrgTicketsResponse> {
const org = await this.requireOrg(projectId, orgId);
const { tickets, invalid } = await listTickets(this.deps, org);
const spend = await computeSpend(this.deps, org, tickets);
const columns = Object.fromEntries(
ORG_TICKET_COLUMNS.map((c) => [c, [] as OrgTicketItem[]]),
) as Record<OrgTicketStatus, OrgTicketItem[]>;
for (const item of this.ticketItems(tickets, spend)) columns[item.status].push(item);
return { columns, invalidFiles: invalid };
}
private async ticketDetail(org: LoadedOrg, ticketId: string): Promise<OrgTicketDetail> {
const { tickets } = await listTickets(this.deps, org);
const spend = await computeSpend(this.deps, org, tickets);
const t = tickets.find((x) => x.ticketId === ticketId);
if (!t) throw ticketNotFound(ticketId);
const item = this.ticketItem(t, spend, new Set(tickets.map((x) => x.ticketId)));
const sessionItems: OrgTicketSessionItem[] = t.doc.sessions.map((sessionId) => {
const row = this.deps.sessions.findById(sessionId);
return {
sessionId,
agentId: row?.agentId ?? "",
...(row?.title ? { title: row.title } : {}),
status: this.deps.runner.statusOf(sessionId),
...(row?.lastActiveAt ? { lastActiveAt: row.lastActiveAt } : {}),
};
});
const file = await this.deps.store.findTicket(org.dir, ticketId);
return {
...item,
goal: t.doc.goal,
acceptanceCriteria: t.doc.acceptanceCriteria,
progress: t.doc.progress,
result: t.doc.result,
history: t.doc.history,
body: file?.raw ?? "",
children: tickets.filter((x) => x.doc.parent === ticketId).map((x) => x.ticketId),
rolledUpCost: spend.ticketRolledUp.get(ticketId) ?? 0,
sessionItems,
};
}
async ticket(projectId: string, orgId: string, ticketId: string): Promise<OrgTicketDetail> {
const org = await this.requireOrg(projectId, orgId);
return this.ticketDetail(org, ticketId);
}
private async requireTicket(org: LoadedOrg, ticketId: string): Promise<LoadedTicket> {
if (!TICKET_ID_PATTERN.test(ticketId)) throw ticketNotFound(ticketId);
const file = await this.deps.store.findTicket(org.dir, ticketId);
if (file === null) throw ticketNotFound(ticketId);
if (!file.parsed.ok)
throw new HttpError(
409,
"ticket_invalid",
`Ticket ${ticketId} needs repair: ${file.parsed.error}`,
);
return { ticketId, column: file.column, relPath: file.relPath, doc: file.parsed.value };
}
/**
* Refuses a parent that already sits under the ticket. Nothing downstream survives a loop:
* the cost roll-up memoizes after its recursion rather than before, so a two-ticket cycle
* recurses to the depth bound and leaves both tickets reporting many times the pair's real
* spend. The walk is bounded by the ids it has already seen, so a cycle a hand edit put on
* disk cannot hang the request that would refuse to deepen it.
*/
private async requireNoParentCycle(
org: LoadedOrg,
ticketId: string,
parent: string,
): Promise<void> {
const seen = new Set<string>();
let cur: string | undefined = parent;
while (cur !== undefined && !seen.has(cur)) {
if (cur === ticketId) throw badRequest(`parent line of ${ticketId} forms a cycle`);
seen.add(cur);
const file = await this.deps.store.findTicket(org.dir, cur);
cur = file !== null && file.parsed.ok ? file.parsed.value.parent : undefined;
}
}
private requirePerson(raw: string, label: string): string {
const p = parsePrincipal(raw);
if (p === null || (p.kind !== "agent" && p.kind !== "user")) {
throw badRequest(`${label} must be agent:<id> or user:<id>.`);
}
return raw.trim();
}
/**
* `owner`: the one principal responsible for the ticket. A bare Agent id or `agent:<id>`
* has to be an employee and `user:<id>` a Project member — a ticket owned by somebody the
* organization does not have is a ticket nobody can be notified about, and nobody can start
* a session for.
*/
private requireOwner(org: LoadedOrg, raw: string): string {
const value = raw.trim();
const parsed = parsePrincipal(value);
if (parsed === null && org.byId.has(value)) return agentPrincipal(value);
if (parsed?.kind === "agent" && org.byId.has(parsed.id)) return agentPrincipal(parsed.id);
if (parsed?.kind === "user" && this.projectUserIds(org).includes(parsed.id)) {
return userPrincipal(parsed.id);
}
throw badRequest(
`owner must be an employee of ${org.orgId} (an Agent id or agent:<id>) or a member of this Project (user:<id>): ${raw}`,
);
}
/**
* The `notify` list a ticket gets when nobody named one: an employee owner is told at its
* desk, so it defaults to itself; a person is not, because one @-mention per closed ticket
* is a badge nobody asked for — a person who wants to be told lists itself.
*/
private defaultNotify(owner: string): string[] {
return defaultTicketNotify(owner);
}
/** One history entry appended to the ticket; every write leaves exactly one. */
private recordHistory(
doc: TicketDoc,
by: string,
action: OrgTicketHistoryAction,
note?: string,
): void {
doc.history = [
...doc.history,
{
at: new Date(this.now()).toISOString(),
by,
action,
...(note !== undefined && note !== "" ? { note } : {}),
},
];
}
/**
* Books the calling session as a contributing session of the ticket. A write that claims
* work — a progress line, an edit of the body, the move into `review` — from inside one of
* this organization's sessions puts that session on the ticket's `sessions` list, so its
* cost is split onto the ticket: a desk that did the work at its own table is at least paid
* for out of the ticket's budget. Management writes (accepting, closing, blocking,
* unblocking) book nothing — a CEO's desk that accepts twenty tickets has not worked on
* twenty tickets. Mutates `doc`; returns the session booked, or null when there was none.
*/
private bookSession(
org: LoadedOrg,
actor: Actor,
doc: TicketDoc,
): { sessionId: string; agentId: string } | null {
const sessionId = actor.sessionId;
if (sessionId === undefined) return null;
const agentId = principalAgentId(this.actorPrincipal(org, actor));
if (agentId === null || doc.sessions.includes(sessionId)) return null;
doc.sessions = [...doc.sessions, sessionId];
return { sessionId, agentId };
}
/** The cache twin of `bookSession`: the projection a write outside a reconcile would not refresh. */
private cacheBookedSession(
org: LoadedOrg,
ticketId: string,
booked: { sessionId: string; agentId: string } | null,
): void {
if (booked === null) return;
this.deps.cache.addTicketSession(
org.projectId,
org.orgId,
ticketId,
booked.sessionId,
booked.agentId,
);
}
/**
* The slug half of a new ticket id. `slug` as given always wins, validated against the
* pattern the id carries. Otherwise the title is slugified; a title that yields fewer than
* two words carries too little meaning to name the work — which is every title written in
* a language with no Latin letters — so the Project's model is asked for an English one,
* with a single retry when its answer sanitizes to nothing. When there is no model, or it
* cannot name it either, the caller is told to pass `--slug` rather than given a ticket
* called `t-4f2a`: a ticket id is read by people for the life of the organization.
*/
private async ticketSlug(
projectId: string,
title: string,
requested: string | undefined,
): Promise<string> {
if (requested !== undefined && requested.trim() !== "") {
const slug = requested.trim().toLowerCase();
if (!TICKET_SLUG_PATTERN.test(slug)) {
throw badRequest(
`slug must be lowercase English words joined by hyphens: ${requested.trim()}`,
);
}
return slug;
}
const fromTitle = slugify(title);
if (fromTitle.includes("-")) return fromTitle;
const complete = this.deps.completeOnce;
if (complete !== undefined) {
const base = ticketSlugPrompt(title);
for (const prompt of [base, `${base} ${TICKET_SLUG_RETRY_RULE}`]) {
const res = await complete(projectId, prompt);
if (!res.ok) {
this.deps.log?.(`org: ticket slug for "${title}" fell back: ${res.error}`);
break;
}
const proposed = slugify(firstLine(res.text));
if (proposed !== "") return proposed;
}
}
if (fromTitle !== "") return fromTitle;
throw new HttpError(
400,
"slug_required",
"pass --slug: lowercase English words joined by hyphens",
);
}
async createTicket(
projectId: string,
orgId: string,
req: OrgTicketCreateRequest,
actor: Actor,
): Promise<OrgTicketDetail> {
const ticketId = await this.scheduler.withLock(projectId, orgId, async () => {
const org = await this.requireValidOrg(projectId, orgId);
const title = req.title.trim();
if (title === "") throw badRequest("title must not be empty.");
const by = this.actorPrincipal(org, actor);
const owner =
req.owner !== undefined && req.owner.trim() !== "" ? this.requireOwner(org, req.owner) : by;
// The model ask that names an untitled-in-English ticket runs under the organization's
// lock: filing a ticket is rare, and a slug settled outside it could collide with one
// filed meanwhile.
const slug = await this.ticketSlug(projectId, title, req.slug);
const date = zonedDate(org.config.timezone, this.now());
let id = `${date}-${slug}`;
for (let n = 2; (await this.deps.store.findTicket(org.dir, id)) !== null; n++) {
id = `${date}-${slug}-${slugSuffix(n)}`;
}
if (
req.parent !== undefined &&
(await this.deps.store.findTicket(org.dir, req.parent)) === null
) {
throw badRequest(`Parent ticket does not exist: ${req.parent}`);
}
const notify = (req.notify ?? []).map((n) => this.requirePerson(n, "notify"));
const doc: TicketDoc = {
title,
status: "proposed",
owner,
...(req.parent !== undefined ? { parent: req.parent } : {}),
notify: notify.length > 0 ? notify : this.defaultNotify(owner),
priority: req.priority ?? "P2",
...(req.due !== undefined ? { due: req.due } : {}),
sessions: [],
history: [],
goal: (req.body ?? req.goal ?? "").trim(),
acceptanceCriteria: req.body !== undefined ? "" : (req.acceptanceCriteria ?? "").trim(),
progress: [],
result: "",
extra: {},
extraSections: [],
};
this.recordHistory(doc, by, "created");
// Filing for somebody else is two facts: who filed it, and who it landed on.
if (owner !== by) this.recordHistory(doc, by, "assigned", owner);
// Baseline the notice state with no owner, so the owner is noticed as an assignment.
this.deps.cache.upsertTicketState({
projectId,
orgId,
ticketId: id,
status: "proposed",
owner: "",
blocked: "",
blockedBy: "",
});
await this.deps.store.writeTicket(org.dir, id, "proposed", doc);
this.deps.notifyProject(projectId, {
type: "org_ticket",
projectId,
orgId,
ticketId: id,
change: "created",
});
return id;
});
await this.scheduler.reconcile(projectId, orgId);
return this.ticket(projectId, orgId, ticketId);
}
async updateTicket(
projectId: string,
orgId: string,
ticketId: string,
req: OrgTicketUpdateRequest,
actor: Actor,
): Promise<OrgTicketDetail> {
await this.scheduler.withLock(projectId, orgId, async () => {
const org = await this.requireValidOrg(projectId, orgId);
const t = await this.requireTicket(org, ticketId);
const d = t.doc;
const by = this.actorPrincipal(org, actor);
// The fields the edit actually changed, for the history entry that records it.
const changed: string[] = [];
if (req.title !== undefined) {
if (req.title.trim() === "") throw badRequest("title must not be empty.");
if (d.title !== req.title.trim()) changed.push("title");
d.title = req.title.trim();
}
let assigned: string | null = null;
if (req.owner !== undefined && req.owner.trim() !== "") {
const owner = this.requireOwner(org, req.owner);
if (owner !== d.owner) assigned = owner;
d.owner = owner;
}
if (req.parent === null) {
if (d.parent !== undefined) changed.push("parent");
delete d.parent;
} else if (req.parent !== undefined) {
if (
req.parent === ticketId ||
(await this.deps.store.findTicket(org.dir, req.parent)) === null
) {
throw badRequest(`Parent ticket does not exist: ${req.parent}`);
}
await this.requireNoParentCycle(org, ticketId, req.parent);
if (d.parent !== req.parent) changed.push("parent");
d.parent = req.parent;
}
if (req.notify !== undefined) {
const notify = req.notify.map((n) => this.requirePerson(n, "notify"));
d.notify = notify.length > 0 ? notify : this.defaultNotify(d.owner);
changed.push("notify");
}
if (req.priority !== undefined) {
if (d.priority !== req.priority) changed.push("priority");
d.priority = req.priority;
}
if (req.due === null) {
if (d.due !== undefined) changed.push("due");
delete d.due;
} else if (req.due !== undefined) {
if (d.due !== req.due) changed.push("due");
d.due = req.due;
}
if (req.goal !== undefined) {
if (d.goal !== req.goal.trim()) changed.push("goal");
d.goal = req.goal.trim();
}
if (req.acceptanceCriteria !== undefined) {
if (d.acceptanceCriteria !== req.acceptanceCriteria.trim())
changed.push("acceptance criteria");
d.acceptanceCriteria = req.acceptanceCriteria.trim();
}
if (req.result !== undefined) {
if (d.result !== req.result.trim()) changed.push("result");
d.result = req.result.trim();
}
// An assignment is its own entry; the rest of the edit is one `edited` entry naming
// the fields, so a ticket assigned and retitled at once reads as the two things it was.
if (assigned !== null) this.recordHistory(d, by, "assigned", assigned);
if (changed.length > 0) this.recordHistory(d, by, "edited", changed.join(", "));
const booked = this.bookSession(org, actor, d);
await this.deps.store.writeTicket(org.dir, ticketId, t.column, d);
this.cacheBookedSession(org, ticketId, booked);
this.deps.notifyProject(projectId, {
type: "org_ticket",
projectId,
orgId,
ticketId,
change: "updated",
});
});
await this.scheduler.reconcile(projectId, orgId);
return this.ticket(projectId, orgId, ticketId);
}
async moveTicket(
projectId: string,
orgId: string,
ticketId: string,
status: OrgTicketStatus,
reason: string | undefined,
actor: Actor,
): Promise<OrgTicketDetail> {
await this.scheduler.withLock(projectId, orgId, async () => {
const org = await this.requireValidOrg(projectId, orgId);
if (!isTicketColumn(status)) throw badRequest("status must be a board column.");
const t = await this.requireTicket(org, ticketId);
if (status === "rejected" && (reason === undefined || reason.trim() === "")) {
throw badRequest("Moving a ticket to rejected needs a reason.");
}
const by = this.actorPrincipal(org, actor);
const d = t.doc;
const from = t.column;
d.status = status;
const why = reason?.trim() ?? "";
if (why !== "") {
d.result = d.result.trim() === "" ? why : `${d.result.trim()}\n\n${why}`;
}
this.recordHistory(d, by, "moved", why === "" ? status : `${status}: ${why}`);
// Handing work in is a claim of work; accepting, closing and rejecting are decisions.
const booked = status === "review" ? this.bookSession(org, actor, d) : null;
await this.deps.store.moveTicket(org.dir, ticketId, from, status, d);
this.cacheBookedSession(org, ticketId, booked);
});
await this.scheduler.reconcile(projectId, orgId);
return this.ticket(projectId, orgId, ticketId);
}
async blockTicket(
projectId: string,
orgId: string,
ticketId: string,
reason: string,
by: string | undefined,
actor: Actor,
): Promise<OrgTicketDetail> {
await this.scheduler.withLock(projectId, orgId, async () => {
const org = await this.requireValidOrg(projectId, orgId);
const t = await this.requireTicket(org, ticketId);
if (reason.trim() === "") throw badRequest("reason must not be empty.");
if (by !== undefined && by !== "") {
const p = parsePrincipal(by);
const isTicket = TICKET_ID_PATTERN.test(by);
if (!isTicket && (p === null || (p.kind !== "agent" && p.kind !== "user"))) {
throw badRequest("by must be a ticket id or agent:<id> / user:<id>.");
}
if (isTicket && (await this.deps.store.findTicket(org.dir, by)) === null) {
throw badRequest(`Blocking ticket does not exist: ${by}`);
}
if (p?.kind === "agent" || p?.kind === "user") {
// A named principal is held to the same chart as a channel member: an
// agent:<id> that names no employee, or a user:<id> outside the Project,
// would still render as "(by …)" in the digest and on the board — an
// attribution nobody can answer for.
this.requireChannelPrincipal(org, by);
}
}
const d = t.doc;
d.blocked = reason.trim();
if (by !== undefined && by !== "") d.blockedBy = by.trim();
else delete d.blockedBy;
this.recordHistory(
d,
this.actorPrincipal(org, actor),
"blocked",
`${reason.trim()}${by ? ` (by ${by.trim()})` : ""}`,
);
await this.deps.store.writeTicket(org.dir, ticketId, t.column, d);
});
await this.scheduler.reconcile(projectId, orgId);
return this.ticket(projectId, orgId, ticketId);
}
async unblockTicket(
projectId: string,
orgId: string,
ticketId: string,
actor: Actor,
): Promise<OrgTicketDetail> {
await this.scheduler.withLock(projectId, orgId, async () => {
const org = await this.requireValidOrg(projectId, orgId);
const t = await this.requireTicket(org, ticketId);
const d = t.doc;
delete d.blocked;
delete d.blockedBy;
this.recordHistory(d, this.actorPrincipal(org, actor), "unblocked");
await this.deps.store.writeTicket(org.dir, ticketId, t.column, d);
});
await this.scheduler.reconcile(projectId, orgId);
return this.ticket(projectId, orgId, ticketId);
}
async progressTicket(
projectId: string,
orgId: string,
ticketId: string,
text: string,
actor: Actor,
): Promise<OrgTicketDetail> {
await this.scheduler.withLock(projectId, orgId, async () => {
const org = await this.requireValidOrg(projectId, orgId);
const t = await this.requireTicket(org, ticketId);
const sentence = text.replace(/\s*\n\s*/g, " ").trim();
if (sentence === "") throw badRequest("text must not be empty.");
// The section is prose: the sentence alone, with who wrote it and when in the history.
t.doc.progress = [...t.doc.progress, sentence];
this.recordHistory(t.doc, this.actorPrincipal(org, actor), "progress", historyNote(sentence));
const booked = this.bookSession(org, actor, t.doc);
await this.deps.store.writeTicket(org.dir, ticketId, t.column, t.doc);
this.cacheBookedSession(org, ticketId, booked);
this.deps.notifyProject(projectId, {
type: "org_ticket",
projectId,
orgId,
ticketId,
change: "progress",
});
});
return this.ticket(projectId, orgId, ticketId);
}
/**
* Opens a ticket session. Who may open one is the ticket's own rule: a person may open a
* session for any ticket, naming the employee with `agentId`; an employee may open one
* only for a ticket it owns. A desk that wants a colleague's ticket worked assigns it and
* lets that desk pick it up in its next sweep — an assignment is how work moves between
* employees, and a session opened around it leaves the owner with work it never saw. The
* owner may still pass `agentId` to enlist a colleague on its OWN ticket, which is how a
* request for help in a channel is answered.
*/
async startTicket(
projectId: string,
orgId: string,
ticketId: string,
req: { agentId?: string; message?: string; workspace?: string },
actor: Actor,
): Promise<{ sessionId: string }> {
const sessionId = await this.scheduler.withLock(projectId, orgId, async () => {
const org = await this.requireValidOrg(projectId, orgId);
const t = await this.requireTicket(org, ticketId);
const owner = principalAgentId(t.doc.owner);
const caller = this.actorEmployee(org, actor);
if (caller !== null && caller !== owner) {
throw new HttpError(
403,
"not_ticket_owner",
owner === null
? `Only the ticket's owner starts its sessions; ${ticketId} has no employee owner — assign an owner first (\`penguin org ticket assign ${ticketId} --owner agent:<employee>\`) and its desk picks it up in its next sweep.`
: `Only the ticket's owner starts its sessions; assign the ticket (\`penguin org ticket assign ${ticketId} --owner agent:<employee>\`) and its desk picks it up in its next sweep.`,
);
}
const agentId = req.agentId ?? owner;
if (agentId === null) {
throw badRequest("The ticket has no employee owner; pass agentId.");
}
if (!org.byId.has(agentId))
throw new HttpError(404, "employee_not_found", `${agentId} is not an employee.`);
const spend = await computeSpend(this.deps, org, (await listTickets(this.deps, org)).tickets);
const r = await openTicketSession(this.deps, org, t, agentId, {
...(req.message !== undefined ? { message: req.message } : {}),
...(req.workspace !== undefined ? { workspace: req.workspace } : {}),
budget: budgetLine(org, spend, agentId),
by: this.actorPrincipal(org, actor),
});
if (!r.ok) throw new HttpError(409, "ticket_session_failed", r.error);
return r.sessionId;
});
await this.scheduler.reconcile(projectId, orgId, { triggers: false });
return { sessionId };
}
async attachTicket(
projectId: string,
orgId: string,
ticketId: string,
sessionId: string,
actor: Actor,
): Promise<OrgTicketDetail> {
await this.scheduler.withLock(projectId, orgId, async () => {
const org = await this.requireValidOrg(projectId, orgId);
const t = await this.requireTicket(org, ticketId);
const row = this.deps.sessions.findById(sessionId);
if (!row || row.projectId !== projectId)
throw new HttpError(404, "session_not_found", `Session does not exist: ${sessionId}`);
// Spend is summed along the reporting line, so a session of an Agent nobody employs
// would land on the ticket's total and in no employee's cumulative — invisible to the
// CEO's cap and to the warn and pause that hang off it. Booking a session implicitly
// is employee-gated already; attaching one by hand is held to the same rule.
if (!org.byId.has(row.agentId)) {
throw new HttpError(
400,
"not_employee_session",
`${sessionId} belongs to ${row.agentId}, who is not an employee of ${org.orgId}.`,
);
}
if (!t.doc.sessions.includes(sessionId)) {
t.doc.sessions = [...t.doc.sessions, sessionId];
this.recordHistory(t.doc, this.actorPrincipal(org, actor), "session_attached", sessionId);
await this.deps.store.writeTicket(org.dir, ticketId, t.column, t.doc);
this.deps.cache.addTicketSession(projectId, orgId, ticketId, sessionId, row.agentId);
this.deps.notifyProject(projectId, {
type: "org_ticket",
projectId,
orgId,
ticketId,
change: "attached",
});
}
});
return this.ticket(projectId, orgId, ticketId);
}
// ---------------------------------------------------------------------------
// Channels
// ---------------------------------------------------------------------------
/** Who is asking: an employee when the call came from one of its sessions, else the signed-in person. */
private caller(
org: LoadedOrg,
actor: Actor,
): { principal: string; agentId: string | null; userId: string | null } {
const principal = this.actorPrincipal(org, actor);
const agentId = principalAgentId(principal);
return { principal, agentId, userId: agentId === null ? actor.userId : null };
}
/** The Project's people: its owner and its members, the `user:` half of the all-hands channel. */
private projectUserIds(org: LoadedOrg): string[] {
const project = this.deps.projects.findById(org.projectId);
const out: string[] = [];
for (const id of [
...(project ? [project.ownerUserId] : []),
...this.deps.members.list(org.projectId).map((m) => m.userId),
]) {
if (!out.includes(id)) out.push(id);
}
return out;
}
/** A channel's membership as principals: the all-hands channel resolves to everyone, the rest to their list. */
private channelMemberPrincipals(org: LoadedOrg, cfg: ChannelConfig): string[] {
if (cfg.everyone !== true) return cfg.members ?? [];
return [
...org.chart.employees.map((e) => agentPrincipal(e.agentId)),
...this.projectUserIds(org).map(userPrincipal),
];
}
/**
* The channel's config, or 404. An unparsable `channel.toml` is skipped everywhere else,
* so it is not there to be read or written either; the reason travels in the message
* rather than in a second error code.
*/
private async requireChannel(org: LoadedOrg, channelId: string): Promise<ChannelConfig> {
if (!isChannelId(channelId)) throw channelNotFound(channelId);
const file = await this.deps.store.readChannel(org.dir, channelId);
if (file === null) throw channelNotFound(channelId);
if (!file.parsed.ok) {
throw new HttpError(
404,
"channel_not_found",
`Channel ${channelId} has an invalid channel.toml: ${file.parsed.error}`,
);
}
return file.parsed.value;
}
/** The last message's time, plus the caller's unread counts when the caller is a person. */
private async channelActivity(
org: LoadedOrg,
channelId: string,
userId: string | null,
): Promise<{ unread: number; mentionsMe: number; lastMessageAt: string | null }> {
const days = await this.deps.store.listMessageDays(org.dir, channelId);
let lastMessageAt: string | null = null;
for (const d of days) {
const list = (await this.deps.store.readMessageDay(org.dir, channelId, d)).messages;
if (list.length > 0) {
lastMessageAt = list.at(-1)!.time;
break;
}
}
// Read cursors belong to people; an employee reads its channel through its trigger.
if (userId === null) return { unread: 0, mentionsMe: 0, lastMessageAt };
const lastReadId = this.deps.cache.readCursor(org.projectId, org.orgId, channelId, userId);
const counts = await this.countUnread(org, channelId, days, userPrincipal(userId), lastReadId);
return { ...counts, lastMessageAt };
}
/**
* What one person has not read in a channel, and how much of it names them. Two rules the
* loop is here to keep in one place:
*
* A person's own lines are never unread. Only `markRead` moves the cursor, so posting from
* the CLI — or from the Web App when the read that follows a post does not land — would
* otherwise leave a person with a badge counting what they just wrote.
*
* The walk stops at the read cursor, not at a fixed number of files. Days come newest
* first and only days with messages have one, so a count that stopped after seven of them
* silently truncated anyone who last read more than seven *active* days ago — the normal
* case for an organization left running for weeks. Ids sort in write order, so the first
* day holding anything at or before the cursor is the cursor's own day and every older day
* is read through. A person who has read nothing has no day to stop at: the whole channel
* is unread and the whole (finite) day list is walked, which is the same bound with the
* cursor at the beginning of time.
*/
private async countUnread(
org: LoadedOrg,
channelId: string,
days: readonly string[],
me: string,
lastReadId: string | null,
loaded?: { date: string; messages: OrgChannelMessage[] },
): Promise<{ unread: number; mentionsMe: number }> {
let unread = 0;
let mentionsMe = 0;
for (const d of days) {
const list =
loaded !== undefined && loaded.date === d
? loaded.messages
: (await this.deps.store.readMessageDay(org.dir, channelId, d)).messages;
let reachedCursor = false;
for (const m of list) {
if (lastReadId !== null && m.id <= lastReadId) {
reachedCursor = true;
continue;
}
if (m.sender === me) continue;
unread++;
if (m.mentions.includes(me)) mentionsMe++;
}
if (reachedCursor) break;
}
return { unread, mentionsMe };
}
private async channelItem(
org: LoadedOrg,
channelId: string,
cfg: ChannelConfig,
caller: { principal: string; userId: string | null },
): Promise<OrgChannelItem> {
const members = this.channelMemberPrincipals(org, cfg);
return {
channelId,
name: cfg.name,
purpose: cfg.purpose,
everyone: cfg.everyone === true,
archived: cfg.archived,
createdBy: cfg.createdBy,
createdAt: cfg.createdAt,
memberCount: members.length,
isMember: members.includes(caller.principal),
...(await this.channelActivity(org, channelId, caller.userId)),
};
}
private async channelMembers(org: LoadedOrg, cfg: ChannelConfig): Promise<OrgChannelMember[]> {
const out: OrgChannelMember[] = [];
for (const principal of this.channelMemberPrincipals(org, cfg)) {
const parsed = parsePrincipal(principal);
if (parsed?.kind === "agent") {
const name = (await this.deps.agents.exists(org.projectId, parsed.id))
? await this.deps.agents.displayName(org.projectId, parsed.id)
: parsed.id;
out.push({ principal, name, kind: "agent" });
} else if (parsed?.kind === "user") {
out.push({ principal, name: parsed.id, kind: "user" });
}
}
return out;
}
private async channelDetail(
org: LoadedOrg,
channelId: string,
cfg: ChannelConfig,
caller: { principal: string; userId: string | null },
): Promise<OrgChannelDetail> {
return {
...(await this.channelItem(org, channelId, cfg, caller)),
members: await this.channelMembers(org, cfg),
};
}
/** People are the board and see every channel; an employee sees the channels it belongs to. */
async channels(projectId: string, orgId: string, actor: Actor): Promise<OrgChannelsResponse> {
const org = await this.requireOrg(projectId, orgId);
const caller = this.caller(org, actor);
const channels: OrgChannelItem[] = [];
for (const file of await this.deps.store.listChannels(org.dir)) {
if (!file.parsed.ok) continue;
const item = await this.channelItem(org, file.channelId, file.parsed.value, caller);
if (caller.agentId !== null && !item.isMember) continue;
channels.push(item);
}
channels.sort((a, b) =>
a.channelId === DEFAULT_CHANNEL_ID
? -1
: b.channelId === DEFAULT_CHANNEL_ID
? 1
: a.name.localeCompare(b.name) || a.channelId.localeCompare(b.channelId),
);
return { channels };
}
/** A new channel holds exactly its creator; everyone else arrives by invitation (people may also join). */
async createChannel(
projectId: string,
orgId: string,
req: OrgChannelCreateRequest,
actor: Actor,
): Promise<OrgChannelItem> {
const channelId = req.channelId;
const item = await this.scheduler.withLock(projectId, orgId, async () => {
const org = await this.requireOrg(projectId, orgId);
if (!isChannelId(channelId)) {
throw badRequest(
"Channel id must be 2–64 characters: a lowercase letter, then lowercase letters, digits or underscores.",
);
}
if ((await this.deps.store.readChannel(org.dir, channelId)) !== null) {
throw new HttpError(409, "channel_exists", `Channel id is already taken: ${channelId}`);
}
const caller = this.caller(org, actor);
const cfg: ChannelConfig = {
name: req.name?.trim() || channelId,
purpose: req.purpose?.trim() ?? "",
createdBy: caller.principal,
createdAt: new Date(this.now()).toISOString(),
archived: false,
members: [caller.principal],
};
await this.deps.store.writeChannel(org.dir, channelId, cfg);
await appendChannelMessage(
this.deps,
org,
channelId,
systemMessage(channelCreated(caller.principal)),
);
return this.channelItem(org, channelId, cfg, caller);
});
await this.scheduler.reconcile(projectId, orgId);
return item;
}
async channel(
projectId: string,
orgId: string,
channelId: string,
actor: Actor,
): Promise<OrgChannelDetail> {
const org = await this.requireOrg(projectId, orgId);
const cfg = await this.requireChannel(org, channelId);
const caller = this.caller(org, actor);
this.requireReadAccess(org, channelId, cfg, caller);
return this.channelDetail(org, channelId, cfg, caller);
}
/** People read every channel; an employee only the ones it belongs to. */
private requireReadAccess(
org: LoadedOrg,
channelId: string,
cfg: ChannelConfig,
caller: { principal: string; agentId: string | null },
): void {
if (caller.agentId === null) return;
if (this.channelMemberPrincipals(org, cfg).includes(caller.principal)) return;
throw notAMember(channelId, caller.principal);
}
async patchChannel(
projectId: string,
orgId: string,
channelId: string,
req: OrgChannelPatchRequest,
actor: Actor,
): Promise<OrgChannelItem> {
const item = await this.scheduler.withLock(projectId, orgId, async () => {
const org = await this.requireOrg(projectId, orgId);
const cfg = await this.requireChannel(org, channelId);
const caller = this.caller(org, actor);
const members = this.channelMemberPrincipals(org, cfg);
if (req.archived !== undefined) {
if (channelId === DEFAULT_CHANNEL_ID) {
throw allHandsImmutable("The all-hands channel cannot be archived.");
}
if (caller.agentId !== null) {
throw notAMember(channelId, caller.principal, "Only people archive a channel.");
}
}
// Everything but lifting the archive itself is refused while the channel is archived.
if (cfg.archived && req.archived !== false) throw channelArchived(channelId);
const renaming = req.name !== undefined || req.purpose !== undefined;
if (renaming && !members.includes(caller.principal)) {
throw notAMember(channelId, caller.principal);
}
const next: ChannelConfig = { ...cfg };
if (req.name !== undefined) {
if (req.name.trim() === "") throw badRequest("name must not be empty.");
next.name = req.name.trim();
}
if (req.purpose !== undefined) next.purpose = req.purpose.trim();
const archiveChanged = req.archived !== undefined && req.archived !== cfg.archived;
// The notice is written before the flag: an archived channel is skipped by the scan,
// so a line written after it would wait for the unarchive to reach the event stream.
if (archiveChanged) {
await appendChannelMessage(
this.deps,
org,
channelId,
systemMessage(channelArchiveChanged(caller.principal, req.archived === true)),
);
next.archived = req.archived === true;
}
await this.deps.store.writeChannel(org.dir, channelId, next);
return this.channelItem(org, channelId, next, caller);
});
await this.scheduler.reconcile(projectId, orgId);
return item;
}
/** `agent:<id>` must be an employee and `user:<id>` a Project member — nobody else can be in a channel. */
private requireChannelPrincipal(org: LoadedOrg, raw: string): string {
const parsed = parsePrincipal(raw);
if (parsed?.kind === "agent" && org.byId.has(parsed.id)) return agentPrincipal(parsed.id);
if (parsed?.kind === "user" && this.projectUserIds(org).includes(parsed.id)) {
return userPrincipal(parsed.id);
}
throw new HttpError(
400,
"invalid_principal",
`Not an employee of ${org.orgId} or a member of this Project: ${raw}`,
);
}
/** Any member invites; a person may also join by itself, an employee may not. */
async addChannelMember(
projectId: string,
orgId: string,
channelId: string,
rawPrincipal: string,
actor: Actor,
): Promise<OrgChannelDetail> {
const detail = await this.scheduler.withLock(projectId, orgId, async () => {
const org = await this.requireOrg(projectId, orgId);
const cfg = await this.requireChannel(org, channelId);
if (channelId === DEFAULT_CHANNEL_ID) {
throw allHandsImmutable("Everyone is in the all-hands channel already.");
}
if (cfg.archived) throw channelArchived(channelId);
const principal = this.requireChannelPrincipal(org, rawPrincipal);
const caller = this.caller(org, actor);
const members = cfg.members ?? [];
if (principal === caller.principal) {
if (caller.agentId !== null) {
throw notAMember(
channelId,
caller.principal,
"An employee joins a channel only when a member invites it.",
);
}
} else if (!members.includes(caller.principal)) {
throw notAMember(channelId, caller.principal);
}
if (members.includes(principal)) return this.channelDetail(org, channelId, cfg, caller);
const next: ChannelConfig = { ...cfg, members: [...members, principal] };
await this.deps.store.writeChannel(org.dir, channelId, next);
await appendChannelMessage(
this.deps,
org,
channelId,
systemMessage(channelMemberAdded(caller.principal, principal)),
);
return this.channelDetail(org, channelId, next, caller);
});
await this.scheduler.reconcile(projectId, orgId);
return detail;
}
/** A member removes itself; a person may remove anyone. Removing a non-member changes nothing. */
async removeChannelMember(
projectId: string,
orgId: string,
channelId: string,
rawPrincipal: string,
actor: Actor,
): Promise<void> {
await this.scheduler.withLock(projectId, orgId, async () => {
const org = await this.requireOrg(projectId, orgId);
const cfg = await this.requireChannel(org, channelId);
if (channelId === DEFAULT_CHANNEL_ID) {
throw allHandsImmutable("Nobody leaves the all-hands channel.");
}
if (cfg.archived) throw channelArchived(channelId);
const parsed = parsePrincipal(rawPrincipal);
if (parsed?.kind !== "agent" && parsed?.kind !== "user") {
throw new HttpError(400, "invalid_principal", `Not a principal: ${rawPrincipal}`);
}
const principal =
parsed.kind === "agent" ? agentPrincipal(parsed.id) : userPrincipal(parsed.id);
const caller = this.caller(org, actor);
if (caller.agentId !== null && principal !== caller.principal) {
throw notAMember(
channelId,
caller.principal,
"An employee removes only itself from a channel.",
);
}
const members = cfg.members ?? [];
if (!members.includes(principal)) return;
await this.deps.store.writeChannel(org.dir, channelId, {
...cfg,
members: members.filter((m) => m !== principal),
});
await appendChannelMessage(
this.deps,
org,
channelId,
systemMessage(channelMemberRemoved(caller.principal, principal)),
);
});
await this.scheduler.reconcile(projectId, orgId);
}
// ---------------------------------------------------------------------------
// Channel messages
// ---------------------------------------------------------------------------
async channelMessages(
projectId: string,
orgId: string,
actor: Actor,
channelId: string,
opts: { date?: string },
): Promise<OrgChannelMessagesResponse> {
const org = await this.requireOrg(projectId, orgId);
const cfg = await this.requireChannel(org, channelId);
const caller = this.caller(org, actor);
this.requireReadAccess(org, channelId, cfg, caller);
const days = await this.deps.store.listMessageDays(org.dir, channelId);
const today = zonedDate(org.config.timezone, this.now());
const date = opts.date ?? today;
const messages = (await this.deps.store.readMessageDay(org.dir, channelId, date)).messages;
const lastReadId =
caller.userId === null
? null
: this.deps.cache.readCursor(projectId, orgId, channelId, caller.userId);
const me = caller.userId === null ? null : userPrincipal(caller.userId);
const { unread, mentionsMe } =
me === null
? { unread: 0, mentionsMe: 0 }
: await this.countUnread(org, channelId, days, me, lastReadId, { date, messages });
return {
channelId,
date,
days,
messages,
unread,
mentionsMe,
...(lastReadId !== null ? { lastReadId } : {}),
};
}
/** Resolves `@` tokens: employees first, then Project members; the writer disambiguates with a prefix. */
private resolveMentions(org: LoadedOrg, text: string): string[] {
const users = new Set(this.projectUserIds(org));
const out: string[] = [];
const add = (p: string): void => {
if (!out.includes(p)) out.push(p);
};
for (const token of extractMentionTokens(text)) {
if (token.id === "all" && token.prefix === undefined) {
add("all");
continue;
}
if (token.prefix === "agent") {
if (org.byId.has(token.id)) add(agentPrincipal(token.id));
} else if (token.prefix === "user") {
if (users.has(token.id)) add(userPrincipal(token.id));
} else if (org.byId.has(token.id)) {
add(agentPrincipal(token.id));
} else if (users.has(token.id)) {
add(userPrincipal(token.id));
}
}
return out;
}
async sendChannelMessage(
projectId: string,
orgId: string,
userId: string,
channelId: string,
req: OrgChannelMessageSendRequest,
): Promise<OrgChannelMessage> {
const msg = await this.scheduler.withLock(projectId, orgId, async () => {
const org = await this.requireOrg(projectId, orgId);
const text = req.text.trim();
if (text === "") throw badRequest("text must not be empty.");
const cfg = await this.requireChannel(org, channelId);
if (cfg.archived) throw channelArchived(channelId);
let sender = userPrincipal(userId);
let hop = 0;
if (req.sessionId !== undefined) {
const owner = this.deps.cache.ownerOfSession(req.sessionId);
if (owner && owner.projectId === projectId && owner.orgId === orgId) {
sender = agentPrincipal(owner.agentId);
hop = owner.triggerHop + 1;
} else {
const row = this.deps.sessions.findById(req.sessionId);
if (row && row.projectId === projectId && org.byId.has(row.agentId)) {
sender = agentPrincipal(row.agentId);
hop = 1;
}
}
}
const members = this.channelMemberPrincipals(org, cfg);
if (!members.includes(sender)) throw notAMember(channelId, sender);
const mentions = this.resolveMentions(org, text);
// `@all` is the channel's own membership, so only named principals can be outsiders.
const outsiders = mentions.filter((m) => m !== "all" && !members.includes(m));
if (outsiders.length > 0) {
throw new HttpError(
400,
"mention_not_member",
`Not a member of ${channelId}: ${outsiders.join(", ")}. Invite them first, or write in a channel they are in.`,
);
}
const refs = req.refs;
return appendChannelMessage(this.deps, org, channelId, {
sender,
hop,
text,
mentions,
...(refs !== undefined && Object.keys(refs).length > 0 ? { refs } : {}),
});
});
await this.scheduler.reconcile(projectId, orgId);
return msg;
}
async markRead(
projectId: string,
orgId: string,
userId: string,
channelId: string,
upTo: string,
): Promise<void> {
const org = await this.requireOrg(projectId, orgId);
await this.requireChannel(org, channelId);
const current = this.deps.cache.readCursor(projectId, orgId, channelId, userId);
if (current === null || upTo > current)
this.deps.cache.setReadCursor(projectId, orgId, channelId, userId, upTo);
}
// ---------------------------------------------------------------------------
// Finance and sessions
// ---------------------------------------------------------------------------
async finance(projectId: string, orgId: string, period?: string): Promise<OrgFinanceResponse> {
const org = await this.requireOrg(projectId, orgId);
const { tickets } = await listTickets(this.deps, org);
const spend = await computeSpend(this.deps, org, tickets, period);
const marks = new Map(
this.deps.cache.listBudgetStates(projectId, orgId, spend.period).map((s) => [s.agentId, s]),
);
const employees: OrgFinanceResponse["employees"] = [];
for (const e of org.chart.employees) {
const cumulative = spend.cumulative.get(e.agentId) ?? 0;
const mark = marks.get(e.agentId);
employees.push({
agentId: e.agentId,
name: (await this.deps.agents.exists(projectId, e.agentId))
? await this.deps.agents.displayName(projectId, e.agentId)
: e.agentId,
title: e.title,
reportsTo: e.reportsTo,
own: spend.own.get(e.agentId) ?? 0,
cumulative,
...(e.budget !== undefined
? { budget: e.budget, ratio: budgetRatio(cumulative, e.budget) }
: {}),
warned: mark?.warnedAt !== undefined && mark.warnedAt !== null,
paused: mark?.pausedAt !== undefined && mark.pausedAt !== null,
});
}
const daily = await this.deps.usage.dailyCostForSessions(
projectId,
spend.sessionIds,
new Date(spend.range.fromMs).toISOString(),
new Date(spend.range.toMs - 1).toISOString(),
);
return {
period: spend.period,
currency: "USD",
employees,
tickets: tickets.map((t) => ({
ticketId: t.ticketId,
title: t.doc.title,
status: t.doc.status,
...(t.doc.parent !== undefined ? { parent: t.doc.parent } : {}),
cost: spend.ticket.get(t.ticketId) ?? 0,
rolledUp: spend.ticketRolledUp.get(t.ticketId) ?? 0,
})),
daily,
alerts: this.alerts(org, spend.period),
total: spend.cumulative.get(ceoAgentId(orgId)) ?? 0,
unpriced: spend.unpriced,
};
}
async sessions(projectId: string, orgId: string): Promise<OrgSessionsResponse> {
const org = await this.requireOrg(projectId, orgId);
const { tickets } = await listTickets(this.deps, org);
syncCaches(this.deps, org, tickets);
const desks: OrgSessionsResponse["desks"] = [];
for (const e of org.chart.employees) {
const desk = org.desks[e.agentId];
if (!desk) continue;
const row = this.deps.sessions.findById(desk.sessionId);
const messagingChannel = this.deps.messagingChannel(desk.sessionId);
desks.push({
agentId: e.agentId,
name: (await this.deps.agents.exists(projectId, e.agentId))
? await this.deps.agents.displayName(projectId, e.agentId)
: e.agentId,
sessionId: desk.sessionId,
...(row?.title ? { title: row.title } : {}),
status: this.deps.runner.statusOf(desk.sessionId),
workspace: desk.workspace,
...(row?.lastActiveAt ? { lastActiveAt: row.lastActiveAt } : {}),
...(messagingChannel !== null ? { messagingChannel } : {}),
});
}
const ticketGroups: OrgSessionsResponse["tickets"] = [];
for (const t of tickets) {
if (t.doc.sessions.length === 0) continue;
ticketGroups.push({
ticketId: t.ticketId,
title: t.doc.title,
status: t.doc.status,
sessions: t.doc.sessions.map((sessionId) => {
const row = this.deps.sessions.findById(sessionId);
return {
sessionId,
agentId: row?.agentId ?? "",
...(row?.title ? { title: row.title } : {}),
status: this.deps.runner.statusOf(sessionId),
...(row?.lastActiveAt ? { lastActiveAt: row.lastActiveAt } : {}),
};
}),
});
}
return { desks, tickets: ticketGroups };
}
}
// ---------------------------------------------------------------------------
// Texts
// ---------------------------------------------------------------------------
function requireHandbookPath(rel: string): void {
if (!isHandbookFilePath(rel))
throw new HttpError(
400,
"invalid_path",
`${rel} is not a handbook path: plain segments, no hidden files, no traversal.`,
);
}
/** How many rows one inbox list carries: a page, the same cap the overview renders. */
const INBOX_PAGE = 20;
/** The `note` a `moved` history entry carries when a ticket lands in `done`, reason or not. */
const MOVED_TO_DONE = /^done(?::|$)/;
/**
* The time a ticket last moved into `done`, from its history. Null when the history has no
* such entry, which is what a ticket moved by editing its file — or one converted from the
* format that predates the history — looks like.
*/
function lastClosedAt(doc: TicketDoc): string | null {
for (let i = doc.history.length - 1; i >= 0; i -= 1) {
const entry = doc.history[i]!;
if (entry.action === "moved" && MOVED_TO_DONE.test(entry.note ?? "")) return entry.at;
}
return null;
}
/** The first non-empty line of a model's answer, stripped of the marks a model wraps one in. */
function firstLine(answer: string): string {
const line = answer
.split("\n")
.map((l) => l.trim())
.find((l) => l !== "");
return (line ?? "").replace(/^[`"'“”‘’]+|[`"'“”‘’.]+$/g, "");
}
/** Appended on the one retry an unusable slug buys: the answer IS the slug, not a sentence about it. */
const TICKET_SLUG_RETRY_RULE =
"Answer with the slug only — lowercase English words joined by hyphens, nothing else.";
/**
* The prompt behind a model-named ticket slug. A ticket id is read by people for the life of
* the organization, so the ask is for words that name the work rather than a transliteration:
* the common case is a Chinese title, which nothing mechanical can turn into English.
*/
function ticketSlugPrompt(title: string): string {
return [
"You name work items. Given a ticket title, answer with ONE slug of 2–5 English words in",
"kebab-case: lowercase ASCII letters joined by hyphens, no digits, no explanation, nothing",
"else. Translate a non-English title rather than transliterating it. Examples:",
"上线站点 → launch-the-site; 季度财报 → quarterly-financial-report; 招募前端 →",
"hire-a-frontend-engineer.",
`Title: ${title}`,
].join(" ");
}
/** The AGENTS.md written for an Agent created as an employee: who it is in this organization and where the handbook is. */
export function employeeBrief(input: {
orgId: string;
name: string;
mission: string;
agentId: string;
title: string;
reportsTo: string | null;
language: OrgLanguage;
duties?: string;
}): string {
if (input.language === "zh") {
return `# 员工简介
你是 \`${input.agentId}\`,组织 **${input.name}**(\`${input.orgId}\`)的${input.title},向${input.reportsTo === null ? "董事会" : `\`${input.reportsTo}\``}汇报。
使命:${input.mission}
${input.duties !== undefined ? `\n职责:${input.duties}\n` : ""}
本组织的工作语言是中文:频道消息、工单、手册文档与汇报都用中文书写,命令、文件名、id 与字段名保持 ASCII。
你的组织目录是 \`<app_data_dir>/organizations/${input.orgId}/\`。每轮工作开始时先读 \`handbook/README.md\`(组织手册的索引;这个目录是公司的知识库),然后按 \`company-employee\` Skill 行事;头衔属于哪个角色,就再用 \`company-ceo\`、\`company-hr\` 或 \`company-finance\`,做实验或审稿则用 \`company-research\`。在你的会话里,\`penguin org\` 命令已经从环境中知道你的组织、Project、Agent 与当前会话。
`;
}
return `# Employee brief
You are \`${input.agentId}\`, ${input.title} of the organization **${input.name}** (\`${input.orgId}\`), reporting to ${input.reportsTo === null ? "the board" : `\`${input.reportsTo}\``}.
Mission: ${input.mission}
${input.duties !== undefined ? `\nDuties: ${input.duties}\n` : ""}
This organization works in English: channel messages, tickets, handbook documents and reports are written in it; commands, file names, ids and field names stay ASCII.
Your organization directory is \`<app_data_dir>/organizations/${input.orgId}/\`. At the start of every work run read \`handbook/README.md\` (the handbook index; the directory is the company's knowledge base), then follow the \`company-employee\` skill; use \`company-ceo\`, \`company-hr\` or \`company-finance\` when your title is that role, and \`company-research\` when you run experiments or review them. Inside your sessions the \`penguin org\` commands already know your organization, Project, Agent and session from the environment.
`;
}
/** The body of the CEO's initialization work run, in the organization's working language. */
function initBody(org: LoadedOrg): string {
const board = userPrincipal(org.config.createdBy);
const ceo = ceoAgentId(org.orgId);
if (orgLanguage(org.config) === "zh") {
return [
`使命:${org.config.mission}`,
"",
"如果上面的使命说的是「镜像一家现实公司」——为现实同事各建一个数字分身、公司只负责传话——就改按 `company-mirror` Skill 行事,跳过下面这份清单。如果使命是做科研——跑实验、给出结论、写论文——下面的清单照常适用,另按 `company-research` Skill 补两件事:至少招一名不审自己稿的专职审稿人;任何实验循环开始前,负责人都要先在全员频道向董事会申请到资源额度。",
"",
"你是一家全新组织的 CEO,这是它的初始化运行。重要的事由董事会拍板,你负责提案。凡是动到这台机器、要花钱或触及组织之外的事——重负载计算、付费服务、公共工作区之外的写入、不可逆操作、缺少的凭据——每名员工(包括你)都先在全员频道请示董事会再动手(`company-employee` 的「What you may not decide alone」一节)。按顺序完成下面几件事:",
`1. 读手册。然后在全员频道里给董事会(${board})写一份提案——\`penguin org channel send -m "@${board} …"\`——写清你对使命的理解、打算开的工作线与首批工单、打算招募的角色(先人事与财务)及其预算——所有人都用组织的 Model,组织未指定时用 Project 的默认 Model,除非使命为某个角色另行指定,提案里不要提 Model——以及公共工作区怎么划分。以明确的问题结尾,然后结束本轮:董事会答复之前不招人、不排日程、不开工单。`,
`2. 答复会以提及或本会话消息的形式到来。董事会确认后,先招人事与财务——\`penguin org hire --new-agent ${org.orgId}_hr --title HR --reports-to ${ceo} --duties "…"\`,\`${org.orgId}_finance\` 同理——再招确认过的其他角色。`,
"3. 按确认的方案划分公共工作区。你自己在 `ceo/` 里工作,招募时不给 `--workspace` 的员工落在以其 Agent id 命名的子目录里,公共工作区的根目录只放大家共读的共享输入、不是任何人的工位。要换个分区名字再单独分配(`penguin org employee set <agent_id> --workspace <子目录>`);相对子目录会在分配时自动建好。",
"4. 把你自己、人事与财务排进日历(`penguin org calendar add …`),做成轮值表而不是广播:你每天 09:00,人事每三天 10:00,财务每周 16:00(组织时区,写成带偏移量的 ISO 时刻,绝不用 `--start-at now`),此后每招一人就给它一个各自不同的时点。",
"5. 把确认过的工单开进 `proposed`(`penguin org ticket create …`):一个项目级目标一张父工单,每条工作线一张子工单。接受一张工单进入 `in_progress` 时就指派负责人(`penguin org ticket assign <id> --owner agent:<员工>`):那名员工的工位会在下一次巡检时接手并发起工单会话。只有工单的负责人可以为它发起会话,所以你只为自己名下的工单执行 `penguin org ticket start <id>`;工位只负责调度与跟踪,绝不在工位上做工单本身的活。",
"6. 每条工作线开一个频道(`penguin org channel create ch_<工作线> --name …`)并邀请它的负责人(`penguin org channel invite ch_<工作线> agent:<agent_id>`),免得一条线索淹没全员频道。",
`7. 在全员频道里向董事会汇报并 @${board},如果还需要拍板,就点明下一个决定。`,
].join("\n");
}
return [
`Mission: ${org.config.mission}`,
"",
"If the mission above says the organization MIRRORS a real company — one digital twin per real colleague, a company that only relays between people — follow the `company-mirror` skill instead and skip the checklist below. If it is a research mission — experiments to run, results to claim, papers to write — the checklist applies and the `company-research` skill adds two things: at least one dedicated reviewer who authors nothing it reviews, and no experiment loop before its owner has an approved resource envelope from the board.",
"",
'You are the CEO of a brand-new organization and this is its initialization run. The board decides the important things; you propose. Whatever touches this machine, spends money or reaches outside the organization — heavy compute, paid services, writing outside the shared workspace, anything irreversible, a missing credential — every employee, you included, asks the board in the all-hands channel before it starts (`company-employee`, "What you may not decide alone"). Work through the following, in order:',
`1. Read the handbook. Then write ONE proposal to the board (${board}) in the all-hands channel — \`penguin org channel send -m "@${board} …"\` — with your reading of the mission, the streams and first tickets you intend to file, the roles you intend to hire (HR and finance first) with budgets — every one on the organization's model, or the Project's default model when the organization names none, unless the mission asked for a particular one on a role, so propose no models — and how you will split the shared workspace. End with the explicit question and END THIS RUN: hire nothing, schedule nothing and file nothing before the board answers.`,
`2. The answer arrives as a mention or in this conversation. Once the board confirms, hire HR and finance first — \`penguin org hire --new-agent ${org.orgId}_hr --title HR --reports-to ${ceo} --duties "…"\` and the same for \`${org.orgId}_finance\` — then the confirmed roles.`,
"3. Partition the shared workspace as confirmed. You already work in `ceo/`, and a hire given no `--workspace` lands in a sub-directory named after its Agent id; the root of the shared workspace holds the shared inputs everyone reads and is nobody's desk. Assign a different sub-directory where a partition should be named for the stream rather than the employee (`penguin org employee set <agent_id> --workspace <sub-directory>`); a relative sub-directory is created when you assign it.",
"4. Put yourself, HR and finance on the calendar (`penguin org calendar add …`) as a rota, not a broadcast: you daily at 09:00, HR every three days at 10:00, finance weekly at 16:00 (organization timezone, ISO instants with the offset — never `--start-at now`), and give every later hire its own distinct hour.",
"5. File the confirmed tickets in `proposed` (`penguin org ticket create …`): one parent ticket for the project-level goal and children per stream. Assign an owner as you accept one into `in_progress` (`penguin org ticket assign <id> --owner agent:<employee>`): that employee's desk picks it up in its next sweep and starts the ticket session itself. Only a ticket's owner may start its sessions, so run `penguin org ticket start <id>` for the tickets you own yourself — the desk schedules and tracks, and never does the ticket work itself.",
"6. Open one channel per stream (`penguin org channel create ch_<stream> --name …`) and invite its owner (`penguin org channel invite ch_<stream> agent:<agent_id>`), so a stream's thread does not drown the all-hands channel.",
`7. Report to the board in the all-hands channel, mentioning @${board}, and name the next decision you need, if any.`,
].join("\n");
}
/** Next scheduled fire time, as the schedules route computes it. */
function calendarNextFireAt(
def: ScheduleDefinition,
state: {
invalidReason: string | null;
firedOnce: boolean;
missed: boolean;
lastSlotMs: number | null;
} | null,
nowMs: number,
): string | undefined {
if (!def.enabled || state?.invalidReason) return undefined;
if (def.periodMs === undefined && state && (state.firedOnce || state.missed)) return undefined;
const due = latestSlotAt(def, nowMs);
if (
due !== null &&
slotInWindow(def, due) &&
(state === null || state.lastSlotMs === null || due > state.lastSlotMs)
) {
return new Date(due).toISOString();
}
const next = nextSlotAfter(def, nowMs);
return next !== null ? new Date(next).toISOString() : undefined;
}
function calendarStatus(
def: ScheduleDefinition,
state: { invalidReason: string | null; firedOnce: boolean; missed: boolean } | null,
nowMs: number,
): ScheduleStatus {
if (state?.invalidReason) return "invalid";
if (def.periodMs === undefined && state?.firedOnce) return "done";
if (def.periodMs === undefined && state?.missed) return "missed";
if (def.endAtMs !== undefined && nowMs > def.endAtMs) return "expired";
return def.enabled ? "active" : "disabled";
}
/**
* What the organization routes need of the runtime — declared where they consume it, so
* the route group names one node instead of reaching into a bag.
*/
export abstract class OrgService extends Interface<
Pick<
OrganizationService,
| "list"
| "create"
| "detail"
| "delete"
| "patch"
| "leave"
| "suggestId"
| "chart"
| "hire"
| "patchEmployee"
| "desk"
| "sessions"
| "calendar"
| "upsertCalendar"
| "deleteCalendar"
| "tickets"
| "ticket"
| "createTicket"
| "updateTicket"
| "moveTicket"
| "blockTicket"
| "unblockTicket"
| "progressTicket"
| "startTicket"
| "attachTicket"
| "channels"
| "channel"
| "createChannel"
| "patchChannel"
| "addChannelMember"
| "removeChannelMember"
| "channelMessages"
| "sendChannelMessage"
| "markRead"
| "finance"
| "handbook"
| "writeHandbook"
| "handbookFiles"
| "handbookFile"
| "writeHandbookFile"
| "deleteHandbookFile"
>
>() {}
/** The organization scheduler as the boot sequence drives it (the pass itself is internal). */
export abstract class OrgScheduler extends Interface<
Pick<OrganizationScheduler, "start" | "stop">
>() {}
/**
* Company mode's runtime, assembled over the same narrow seams the schedule scheduler
* uses: the session manager for run state and task start, SessionService for sessions,
* AgentService and AgentConfigService for hiring, UsageService for spend. The scheduler
* is started by the platform's Startup component (one reconcile pass, no backfill) and
* stopped with this App, like every other timer in the tree.
*/
@Module()
export class OrganizationModule {
@Use() private readonly config!: Config;
@Use() private readonly channels!: Channels;
@Use() private readonly clock!: Clock;
@Use() private readonly log!: Log;
@Use() private readonly cache!: OrgCache;
@Use() private readonly projects!: Projects;
@Use() private readonly members!: Members;
@Use() private readonly sessionsRepo!: SessionIndex;
@Use() private readonly runner!: OrgRuns;
@Use() private readonly sessionCreator!: OrgSessions;
@Use() private readonly agentService!: AgentLifecycle;
@Use() private readonly agentConfig!: AgentConfig;
@Use() private readonly agentsRepo!: AgentIndex;
@Use() private readonly projectConfig!: ProjectConfigStore;
@Use() private readonly usage!: UsageQueries;
@Use() private readonly errors!: Errors;
@Use() private readonly settings!: Settings;
@Use() private readonly messagingRepo!: MessagingBindings;
@Provide() orgService!: OrgService;
@Provide() orgScheduler!: OrgScheduler;
setup({ effect }: ClassCtx) {
const channels = this.channels as ChannelHub;
const agentService = this.agentService;
const agentConfig = this.agentConfig;
const agentsRepo = this.agentsRepo;
const runner = this.runner;
const projectConfig = this.projectConfig;
const deps: OrgDeps = {
root: this.config.root,
store: new OrgStore(this.config.root),
cache: this.cache,
projects: this.projects,
members: this.members,
sessions: this.sessionsRepo,
runner,
sessionCreator: this.sessionCreator,
agents: {
exists: async (projectId, agentId) =>
agentsRepo.exists(projectId, agentId) || agentConfig.exists(projectId, agentId),
create: async (projectId, agentId, name, description, plugins) => {
await agentService.createAgent(projectId, agentId, name, description, plugins);
},
displayName: async (projectId, agentId) =>
(await agentConfig.readCardMeta(projectId, agentId)).name ?? agentId,
writeAgentsMd: (projectId, agentId, content) =>
agentConfig.updateConfig(projectId, agentId, { agentsMd: content }),
pluginVersion: (projectId, agentId, plugin) =>
agentService.pluginVersion(projectId, agentId, plugin),
updatePlugin: async (projectId, agentId, plugin) => {
await agentService.updatePlugin(projectId, agentId, plugin);
// Same reason the plugins route invalidates: a hook package is bound when a core
// Session is built, so a runtime cached for this employee would keep the old set
// until it was evicted. A Task in flight keeps what it started with.
runner.invalidateAgentRuntimes(projectId, agentId);
},
},
projectConfig,
completeOnce: (projectId, prompt) => projectConfig.completeOnce(projectId, prompt),
usage: this.usage,
messagingChannel: (sessionId) => enabledMessagingChannel(this.messagingRepo, sessionId),
errors: this.errors,
notifyProject: (projectId, event) => {
const ownerUserId = this.projects.findById(projectId)?.ownerUserId;
if (ownerUserId === undefined) return;
const audience = new Set([
ownerUserId,
...this.members.list(projectId).map((m) => m.userId),
]);
for (const userId of audience) {
channels.peek(userChannelKey(userId))?.publish(event, "server_event");
}
},
companyModeEnabled: () => this.settings.getCompanyMode(),
now: () => this.clock.now().getTime(),
log: (line: string) => this.log.line(line),
};
const orgScheduler = new OrganizationScheduler(deps);
this.orgScheduler = orgScheduler;
const service = new OrganizationService(deps, orgScheduler);
this.orgService = service;
// An employee's model is its desk Session's: a switch made on a desk reaches the chart.
const unsubscribe = runner.onModelChanged((sessionId, model) => {
service.deskModelChanged(sessionId, model).catch((err: unknown) =>
deps.errors.record({
source: "organization",
err,
code: "org_desk_model_sync_failed",
ctx: { sessionId },
}),
);
});
effect(() => unsubscribe());
// Only active while this App is; the successor's start() reconciles from the files.
effect(() => orgScheduler.stop());
}
}