@codex-modules/teams 0.1.1

package/dist/team.js

@@ -0,0 +1,175 @@
+import { readFileSync, writeFileSync } from "node:fs";
+export const TEAM_NAME_RE = /^[a-z][a-z0-9-]{0,40}$/;
+export const MEMBER_NAME_RE = /^[a-z][a-z0-9-]{0,30}$/;
+const SANDBOXES = new Set(["read-only", "workspace-write"]);
+const LENSES = new Set(["area", "ownership", "perspective"]);
+export function parseTeamJson(path) {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return validateTeamDef(parsed, path);
+}
+export function validateTeamDef(value, label = "team.json") {
+    const errors = collectTeamErrors(value);
+    if (errors.length > 0)
+        throw new Error(`${label} is invalid:\n- ${errors.join("\n- ")}`);
+    return value;
+}
+export function collectTeamErrors(value) {
+    const errors = [];
+    if (!isRecord(value))
+        return ["team definition must be an object"];
+    if (value.version !== 1)
+        errors.push("version must be 1");
+    if (typeof value.name !== "string" || !TEAM_NAME_RE.test(value.name)) {
+        errors.push("name must match ^[a-z][a-z0-9-]{0,40}$");
+    }
+    if (value.description !== undefined && typeof value.description !== "string") {
+        errors.push("description must be a string when present");
+    }
+    if (value.defaults !== undefined) {
+        if (!isRecord(value.defaults))
+            errors.push("defaults must be an object when present");
+        else {
+            if (value.defaults.model !== undefined && value.defaults.model !== null && !nonEmptyString(value.defaults.model)) {
+                errors.push("defaults.model must be a non-empty string when present");
+            }
+            if (value.defaults.sandbox_mode !== undefined &&
+                value.defaults.sandbox_mode !== null &&
+                !SANDBOXES.has(value.defaults.sandbox_mode)) {
+                errors.push("defaults.sandbox_mode must be read-only or workspace-write");
+            }
+        }
+    }
+    if (!Array.isArray(value.members)) {
+        errors.push("members must be an array");
+        return errors;
+    }
+    if (value.members.length < 2 || value.members.length > 8)
+        errors.push("members must contain 2 to 8 entries");
+    const seen = new Set();
+    value.members.forEach((member, index) => {
+        const prefix = `members[${index}]`;
+        if (!isRecord(member)) {
+            errors.push(`${prefix} must be an object`);
+            return;
+        }
+        if (typeof member.name !== "string" || !MEMBER_NAME_RE.test(member.name)) {
+            errors.push(`${prefix}.name must match ^[a-z][a-z0-9-]{0,30}$`);
+        }
+        else if (seen.has(member.name)) {
+            errors.push(`${prefix}.name duplicates ${member.name}`);
+        }
+        else {
+            seen.add(member.name);
+        }
+        if (!nonEmptyString(member.focus))
+            errors.push(`${prefix}.focus is required`);
+        if (!LENSES.has(String(member.lens)))
+            errors.push(`${prefix}.lens must be area, ownership, or perspective`);
+        if (!nonEmptyString(member.deliverable))
+            errors.push(`${prefix}.deliverable is required`);
+        if (member.model !== undefined && member.model !== null && !nonEmptyString(member.model)) {
+            errors.push(`${prefix}.model must be a non-empty string when present`);
+        }
+        if (member.sandbox_mode !== undefined &&
+            member.sandbox_mode !== null &&
+            !SANDBOXES.has(member.sandbox_mode)) {
+            errors.push(`${prefix}.sandbox_mode must be read-only or workspace-write`);
+        }
+        if (member.instructions !== undefined && member.instructions !== null && typeof member.instructions !== "string") {
+            errors.push(`${prefix}.instructions must be a string when present`);
+        }
+    });
+    return errors;
+}
+export function scaffoldTeam(preset = "review-panel") {
+    if (preset === "swarm") {
+        return {
+            version: 1,
+            name: "swarm",
+            description: "Parallel exploration team",
+            defaults: { model: "gpt-5.4-mini", sandbox_mode: "read-only" },
+            members: [1, 2, 3].map(n => ({
+                name: `explorer-${n}`,
+                focus: `independent exploration slice ${n}`,
+                lens: "area",
+                deliverable: "concise evidence-backed notes with file references",
+            })),
+        };
+    }
+    if (preset === "pipeline") {
+        return {
+            version: 1,
+            name: "pipeline",
+            description: "Builder and verifier gated workflow",
+            defaults: { model: "gpt-5.4-mini", sandbox_mode: "workspace-write" },
+            members: [
+                {
+                    name: "builder",
+                    focus: "smallest implementation that satisfies the requested contract",
+                    lens: "ownership",
+                    deliverable: "changed files and verification notes",
+                },
+                {
+                    name: "verifier",
+                    focus: "behavioral regressions, missing tests, and contract drift",
+                    lens: "perspective",
+                    deliverable: "pass/fail findings with exact reproduction steps",
+                    sandbox_mode: "read-only",
+                },
+            ],
+        };
+    }
+    return {
+        version: 1,
+        name: "review-panel",
+        description: "Adversarial review panel",
+        defaults: { model: "gpt-5.4-mini", sandbox_mode: "read-only" },
+        members: [
+            {
+                name: "security",
+                focus: "auth, injection, filesystem, and permission surfaces of the change",
+                lens: "perspective",
+                deliverable: "findings list with file:line, severity, and exploit path",
+            },
+            {
+                name: "correctness",
+                focus: "runtime behavior, edge cases, and data contract mismatches",
+                lens: "area",
+                deliverable: "reproducible bugs with expected versus actual behavior",
+            },
+            {
+                name: "simplicity",
+                focus: "unnecessary abstractions, ownership confusion, and deletion opportunities",
+                lens: "ownership",
+                deliverable: "specific simplifications and the files they affect",
+            },
+        ],
+    };
+}
+export function writePreset(path, preset) {
+    writeFileSync(path, `${JSON.stringify(scaffoldTeam(preset), null, 2)}\n`, { mode: 0o600 });
+}
+export function memberAgentName(team, member) {
+    const teamName = typeof team === "string" ? team : team.name;
+    const memberName = typeof member === "string" ? member : member.name;
+    if (!TEAM_NAME_RE.test(teamName))
+        throw new Error(`invalid team name: ${teamName}`);
+    if (!MEMBER_NAME_RE.test(memberName))
+        throw new Error(`invalid member name: ${memberName}`);
+    return `${teamName}-${memberName}`;
+}
+export function resolveMemberModel(team, member) {
+    const model = member.model ?? team.defaults?.model;
+    if (!model)
+        throw new Error(`member ${member.name} has no model and defaults.model is not set`);
+    return model;
+}
+export function resolveMemberSandbox(team, member) {
+    return member.sandbox_mode ?? team.defaults?.sandbox_mode ?? "read-only";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}

package/dist/toml.d.ts

@@ -0,0 +1,3 @@
+export type TomlPrimitive = string | string[];
+export declare function renderToml(values: Record<string, TomlPrimitive>): string;
+export declare function tomlBasicString(value: string): string;

package/dist/toml.js

@@ -0,0 +1,38 @@
+export function renderToml(values) {
+    return `${Object.entries(values)
+        .map(([key, value]) => `${assertSafeKey(key)} = ${renderValue(value)}`)
+        .join("\n")}\n`;
+}
+export function tomlBasicString(value) {
+    let rendered = '"';
+    for (const char of value.replace(/\r\n/g, "\n").replace(/\r/g, "\n")) {
+        const code = char.charCodeAt(0);
+        if (char === "\b")
+            rendered += "\\b";
+        else if (char === "\t")
+            rendered += "\\t";
+        else if (char === "\n")
+            rendered += "\\n";
+        else if (char === "\f")
+            rendered += "\\f";
+        else if (char === '"')
+            rendered += '\\"';
+        else if (char === "\\")
+            rendered += "\\\\";
+        else if (code === 0x7f || code < 0x20)
+            rendered += `\\u${code.toString(16).padStart(4, "0")}`;
+        else
+            rendered += char;
+    }
+    return `${rendered}"`;
+}
+function renderValue(value) {
+    if (Array.isArray(value))
+        return `[${value.map(tomlBasicString).join(", ")}]`;
+    return tomlBasicString(value);
+}
+function assertSafeKey(key) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+        throw new Error(`unsafe TOML key: ${key}`);
+    return key;
+}

package/dist/types.d.ts

@@ -0,0 +1,114 @@
+export type SandboxMode = "read-only" | "workspace-write";
+export type MemberLens = "area" | "ownership" | "perspective";
+export type InstallScope = "user" | "project";
+export type TeamStatus = "active" | "finished";
+export type FinishStatus = "ok" | "partial";
+export type TaskStatus = "open" | "claimed" | "done" | "failed";
+export type JournalKind = "note" | "handoff" | "decision";
+export type TeamDefaults = {
+    model?: string | null;
+    sandbox_mode?: SandboxMode | null;
+};
+export type MemberDef = {
+    name: string;
+    focus: string;
+    lens: MemberLens;
+    deliverable: string;
+    model?: string | null;
+    sandbox_mode?: SandboxMode | null;
+    instructions?: string | null;
+};
+export type TeamDef = {
+    version: 1;
+    name: string;
+    description?: string;
+    defaults?: TeamDefaults;
+    members: MemberDef[];
+};
+export type BoundMember = {
+    agent_id: string;
+    nickname?: string;
+    bound_at: string;
+};
+export type StateFile = {
+    version: 1;
+    team: string;
+    goal: string;
+    status: TeamStatus;
+    leader_session?: string;
+    members: Record<string, BoundMember>;
+    created_at: string;
+    finished_at?: string;
+    finish_status?: FinishStatus;
+};
+export type TaskRecord = {
+    id: string;
+    title: string;
+    detail?: string;
+    depends_on: string[];
+    status: TaskStatus;
+    claimed_by?: string;
+    lease_expires_at?: string;
+    result?: string;
+    created_at: string;
+    updated_at: string;
+};
+export type TasksFile = {
+    version: 1;
+    tasks: TaskRecord[];
+};
+export type JournalEntry = {
+    ts: string;
+    actor: string;
+    kind: JournalKind;
+    text: string;
+};
+export type ManifestEntry = {
+    team: string;
+    scope: InstallScope | "skill";
+    file: string;
+    backup?: string | null;
+    hash: string;
+    kind: "agent" | "skill";
+    member?: string;
+    installed_at: string;
+};
+export type TeamsManifest = {
+    version: 1;
+    owner: "@codex-modules/teams";
+    entries: ManifestEntry[];
+};
+export type DoctorReport = {
+    codexBinary: string | null;
+    version: string | null;
+    features: Array<{
+        name: string;
+        stage: string;
+        enabled: boolean;
+    }>;
+    featuresError?: string;
+    multiAgent: {
+        present: boolean;
+        stage?: string;
+        enabled?: boolean;
+    };
+    fanout?: {
+        present: boolean;
+        stage?: string;
+        enabled?: boolean;
+    };
+    multiAgentV2?: {
+        present: boolean;
+        stage?: string;
+        enabled?: boolean;
+    };
+    models: {
+        ok: boolean;
+        values: string[];
+        error?: string;
+    };
+    agentsDirWritable: boolean;
+    stateDirWritable: boolean;
+    userInstalledTeams: string[];
+    projectInstalledTeams: string[];
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@codex-modules/teams",
+  "version": "0.1.1",
+  "description": "Team definitions, durable state, and leader prompts for Codex native multi-agent collaboration.",
+  "keywords": [
+    "codex",
+    "openai-codex",
+    "codex-cli",
+    "teams",
+    "multi-agent",
+    "collaboration"
+  ],
+  "license": "MIT",
+  "author": "ArcSolver <hailo.dev01@gmail.com>",
+  "homepage": "https://github.com/ArcSolver/codex-modules/tree/main/modules/teams#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArcSolver/codex-modules.git",
+    "directory": "modules/teams"
+  },
+  "bugs": "https://github.com/ArcSolver/codex-modules/issues",
+  "type": "module",
+  "bin": {
+    "codex-teams": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README.ko.md"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "verify": "bash verify/verify.sh",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.8.3"
+  }
+}