@levelcode/sdk 0.1.0 → 0.2.0

package/dist/common/src/types/team-config-schemas.d.ts

@@ -0,0 +1,213 @@
+import { z } from 'zod';
+export declare const teamRoleSchema: z.ZodEnum<{
+    researcher: "researcher";
+    reviewer: "reviewer";
+    coordinator: "coordinator";
+    cto: "cto";
+    "vp-engineering": "vp-engineering";
+    director: "director";
+    fellow: "fellow";
+    "distinguished-engineer": "distinguished-engineer";
+    "principal-engineer": "principal-engineer";
+    "senior-staff-engineer": "senior-staff-engineer";
+    "staff-engineer": "staff-engineer";
+    manager: "manager";
+    "sub-manager": "sub-manager";
+    "senior-engineer": "senior-engineer";
+    "super-senior": "super-senior";
+    "mid-level-engineer": "mid-level-engineer";
+    "junior-engineer": "junior-engineer";
+    scientist: "scientist";
+    designer: "designer";
+    "product-lead": "product-lead";
+    tester: "tester";
+    intern: "intern";
+    apprentice: "apprentice";
+}>;
+export declare const devPhaseSchema: z.ZodEnum<{
+    planning: "planning";
+    "pre-alpha": "pre-alpha";
+    alpha: "alpha";
+    beta: "beta";
+    production: "production";
+    mature: "mature";
+}>;
+export declare const teamMemberSchema: z.ZodObject<{
+    agentId: z.ZodString;
+    name: z.ZodString;
+    role: z.ZodEnum<{
+        researcher: "researcher";
+        reviewer: "reviewer";
+        coordinator: "coordinator";
+        cto: "cto";
+        "vp-engineering": "vp-engineering";
+        director: "director";
+        fellow: "fellow";
+        "distinguished-engineer": "distinguished-engineer";
+        "principal-engineer": "principal-engineer";
+        "senior-staff-engineer": "senior-staff-engineer";
+        "staff-engineer": "staff-engineer";
+        manager: "manager";
+        "sub-manager": "sub-manager";
+        "senior-engineer": "senior-engineer";
+        "super-senior": "super-senior";
+        "mid-level-engineer": "mid-level-engineer";
+        "junior-engineer": "junior-engineer";
+        scientist: "scientist";
+        designer: "designer";
+        "product-lead": "product-lead";
+        tester: "tester";
+        intern: "intern";
+        apprentice: "apprentice";
+    }>;
+    agentType: z.ZodString;
+    model: z.ZodString;
+    joinedAt: z.ZodNumber;
+    status: z.ZodEnum<{
+        active: "active";
+        idle: "idle";
+        completed: "completed";
+        failed: "failed";
+    }>;
+    currentTaskId: z.ZodOptional<z.ZodString>;
+    cwd: z.ZodString;
+}, z.core.$strip>;
+export declare const teamConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    createdAt: z.ZodNumber;
+    leadAgentId: z.ZodString;
+    phase: z.ZodEnum<{
+        planning: "planning";
+        "pre-alpha": "pre-alpha";
+        alpha: "alpha";
+        beta: "beta";
+        production: "production";
+        mature: "mature";
+    }>;
+    members: z.ZodArray<z.ZodObject<{
+        agentId: z.ZodString;
+        name: z.ZodString;
+        role: z.ZodEnum<{
+            researcher: "researcher";
+            reviewer: "reviewer";
+            coordinator: "coordinator";
+            cto: "cto";
+            "vp-engineering": "vp-engineering";
+            director: "director";
+            fellow: "fellow";
+            "distinguished-engineer": "distinguished-engineer";
+            "principal-engineer": "principal-engineer";
+            "senior-staff-engineer": "senior-staff-engineer";
+            "staff-engineer": "staff-engineer";
+            manager: "manager";
+            "sub-manager": "sub-manager";
+            "senior-engineer": "senior-engineer";
+            "super-senior": "super-senior";
+            "mid-level-engineer": "mid-level-engineer";
+            "junior-engineer": "junior-engineer";
+            scientist: "scientist";
+            designer: "designer";
+            "product-lead": "product-lead";
+            tester: "tester";
+            intern: "intern";
+            apprentice: "apprentice";
+        }>;
+        agentType: z.ZodString;
+        model: z.ZodString;
+        joinedAt: z.ZodNumber;
+        status: z.ZodEnum<{
+            active: "active";
+            idle: "idle";
+            completed: "completed";
+            failed: "failed";
+        }>;
+        currentTaskId: z.ZodOptional<z.ZodString>;
+        cwd: z.ZodString;
+    }, z.core.$strip>>;
+    settings: z.ZodObject<{
+        maxMembers: z.ZodNumber;
+        autoAssign: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const teamTaskSchema: z.ZodObject<{
+    id: z.ZodString;
+    subject: z.ZodString;
+    description: z.ZodString;
+    status: z.ZodEnum<{
+        blocked: "blocked";
+        completed: "completed";
+        pending: "pending";
+        in_progress: "in_progress";
+    }>;
+    owner: z.ZodOptional<z.ZodString>;
+    blockedBy: z.ZodArray<z.ZodString>;
+    blocks: z.ZodArray<z.ZodString>;
+    phase: z.ZodEnum<{
+        planning: "planning";
+        "pre-alpha": "pre-alpha";
+        alpha: "alpha";
+        beta: "beta";
+        production: "production";
+        mature: "mature";
+    }>;
+    activeForm: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const teamProtocolMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"idle_notification">;
+    from: z.ZodString;
+    timestamp: z.ZodString;
+    summary: z.ZodOptional<z.ZodString>;
+    completedTaskId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"task_completed">;
+    from: z.ZodString;
+    taskId: z.ZodString;
+    taskSubject: z.ZodString;
+    timestamp: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"shutdown_request">;
+    requestId: z.ZodString;
+    from: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"shutdown_approved">;
+    requestId: z.ZodString;
+    from: z.ZodString;
+    timestamp: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"shutdown_rejected">;
+    requestId: z.ZodString;
+    from: z.ZodString;
+    reason: z.ZodString;
+    timestamp: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"plan_approval_request">;
+    requestId: z.ZodString;
+    from: z.ZodString;
+    planContent: z.ZodString;
+    timestamp: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"plan_approval_response">;
+    requestId: z.ZodString;
+    approved: z.ZodBoolean;
+    feedback: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"message">;
+    from: z.ZodString;
+    to: z.ZodString;
+    text: z.ZodString;
+    summary: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"broadcast">;
+    from: z.ZodString;
+    text: z.ZodString;
+    summary: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodString;
+}, z.core.$strip>], "type">;

package/dist/common/src/types/team-config.d.ts

@@ -1,5 +1,6 @@
 export type TeamRole = 'coordinator' | 'cto' | 'vp-engineering' | 'director' | 'fellow' | 'distinguished-engineer' | 'principal-engineer' | 'senior-staff-engineer' | 'staff-engineer' | 'manager' | 'sub-manager' | 'senior-engineer' | 'super-senior' | 'mid-level-engineer' | 'junior-engineer' | 'researcher' | 'scientist' | 'designer' | 'product-lead' | 'tester' | 'reviewer' | 'intern' | 'apprentice';
 export type DevPhase = 'planning' | 'pre-alpha' | 'alpha' | 'beta' | 'production' | 'mature';
+export type AgentStatus = 'active' | 'idle' | 'working' | 'blocked' | 'completed' | 'failed';
 export interface TeamMember {
     agentId: string;
     name: string;
@@ -7,7 +8,7 @@ export interface TeamMember {
     agentType: string;
     model: string;
     joinedAt: number;
-    status: 'active' | 'idle' | 'completed' | 'failed';
+    status: AgentStatus;
     currentTaskId?: string;
     cwd: string;
 }
@@ -23,11 +24,13 @@ export interface TeamConfig {
         autoAssign: boolean;
     };
 }
+export type TaskPriority = 'critical' | 'high' | 'medium' | 'low';
 export interface TeamTask {
     id: string;
     subject: string;
     description: string;
     status: 'pending' | 'in_progress' | 'completed' | 'blocked';
+    priority: TaskPriority;
     owner?: string;
     blockedBy: string[];
     blocks: string[];

package/dist/common/src/types/team-hook-events.d.ts

@@ -0,0 +1,36 @@
+import type { DevPhase } from './team-config';
+/**
+ * Hook event fired when an agent goes idle (no active tasks).
+ */
+export type TeammateIdleHookEvent = {
+    type: 'teammate_idle';
+    agentName: string;
+    teamName: string;
+    lastTaskId?: string;
+    timestamp: number;
+};
+/**
+ * Hook event fired when a task is marked as completed.
+ */
+export type TaskCompletedHookEvent = {
+    type: 'task_completed';
+    taskId: string;
+    taskSubject: string;
+    owner: string;
+    teamName: string;
+    timestamp: number;
+};
+/**
+ * Hook event fired when the team's dev phase changes.
+ */
+export type PhaseTransitionHookEvent = {
+    type: 'phase_transition';
+    teamName: string;
+    fromPhase: DevPhase;
+    toPhase: DevPhase;
+    timestamp: number;
+};
+/**
+ * Union of all team hook event types.
+ */
+export type TeamHookEvent = TeammateIdleHookEvent | TaskCompletedHookEvent | PhaseTransitionHookEvent;

package/dist/common/src/utils/dev-phases.d.ts

@@ -0,0 +1,23 @@
+import type { ToolName } from '../tools/constants.js';
+import type { DevPhase, TeamConfig } from '../types/team-config.js';
+export declare const PHASE_ORDER: readonly DevPhase[];
+export declare function getPhaseOrder(phase: DevPhase): number;
+export declare function canTransition(currentPhase: DevPhase, targetPhase: DevPhase): boolean;
+export declare function transitionPhase(teamConfig: TeamConfig, targetPhase: DevPhase): TeamConfig;
+export declare function getPhaseDescription(phase: DevPhase): string;
+/**
+ * Team tool names that are subject to phase gating.
+ * Non-team tools (read_files, str_replace, etc.) are not gated by dev phase.
+ */
+export declare const TEAM_TOOL_NAMES: readonly ToolName[];
+export declare function getPhaseTools(phase: DevPhase): ToolName[];
+/**
+ * Checks whether a specific tool is allowed in the given dev phase.
+ * Only team tools are gated by phase. Non-team tools always return true.
+ */
+export declare function isToolAllowedInPhase(toolName: string, phase: DevPhase): boolean;
+/**
+ * Returns the minimum phase required to use a given team tool.
+ * Returns null for non-team tools (they are always allowed).
+ */
+export declare function getMinimumPhaseForTool(toolName: string): DevPhase | null;

package/dist/common/src/utils/file-lock.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Acquire an exclusive lock on a file path using a .lock sidecar file.
+ * Returns a release function that must be called when done.
+ *
+ * The lock file contains a timestamp. If the lock is older than `staleMs`,
+ * it is considered abandoned and will be forcibly acquired.
+ */
+export declare function acquireLock(filePath: string, timeout?: number): Promise<() => void>;
+/**
+ * Execute a function while holding an exclusive file lock.
+ * The lock is automatically released when the function completes or throws.
+ */
+export declare function withLock<T>(filePath: string, fn: () => T | Promise<T>): Promise<T>;

package/dist/common/src/utils/team-analytics.d.ts

@@ -0,0 +1,16 @@
+import type { TrackEventFn } from '../types/contracts/analytics';
+import type { Logger } from '../types/contracts/logger';
+import type { DevPhase } from '../types/team-config';
+type TrackingContext = {
+    trackEvent: TrackEventFn;
+    userId: string;
+    logger: Logger;
+};
+export declare function trackTeamCreated(ctx: TrackingContext, teamName: string, memberCount: number): void;
+export declare function trackTeamDeleted(ctx: TrackingContext, teamName: string): void;
+export declare function trackTeammateIdle(ctx: TrackingContext, teamName: string, agentName: string, role: string): void;
+export declare function trackTaskCompleted(ctx: TrackingContext, teamName: string, taskId: string, taskSubject: string, owner: string): void;
+export declare function trackPhaseTransition(ctx: TrackingContext, teamName: string, fromPhase: DevPhase, toPhase: DevPhase): void;
+export declare function trackMessageSent(ctx: TrackingContext, teamName: string, type: 'dm' | 'broadcast' | 'shutdown'): void;
+export declare function trackAgentSpawned(ctx: TrackingContext, teamName: string, role: string, agentName: string): void;
+export {};

package/dist/common/src/utils/team-discovery.d.ts

@@ -0,0 +1,47 @@
+import type { TeamConfig, DevPhase, TeamRole } from '../types/team-config';
+export interface TeamAndAgent {
+    teamName: string;
+    agentName: string;
+    config: TeamConfig;
+}
+export interface AgentTeamContext {
+    teamName: string;
+    agentName: string;
+    role: TeamRole;
+    isLeader: boolean;
+    phase: DevPhase;
+}
+export interface TeamSummary {
+    name: string;
+    phase: DevPhase;
+    memberCount: number;
+}
+/**
+ * Finds the team that an agent belongs to, returning the team name and config.
+ * Matches against both the raw agentId and a "lead-" prefixed variant.
+ */
+export declare function findCurrentTeam(agentId: string): {
+    teamName: string;
+    config: TeamConfig;
+} | null;
+/**
+ * Finds the team and the matched agent name for a given agent identifier.
+ * This is the richer variant that also returns which member name was matched.
+ */
+export declare function findCurrentTeamAndAgent(agentId: string): TeamAndAgent | null;
+/**
+ * Direct lookup of a team by name.
+ */
+export declare function findTeamByName(name: string): TeamConfig | null;
+/**
+ * Lists all teams with summary information.
+ */
+export declare function listAllTeams(): TeamSummary[];
+/**
+ * Returns full context for an agent's team membership including role and leadership status.
+ */
+export declare function getAgentTeamContext(agentId: string): AgentTeamContext | null;
+/**
+ * Checks whether an agent is a member of a specific team.
+ */
+export declare function isAgentInTeam(agentId: string, teamName: string): boolean;

package/dist/common/src/utils/team-fs.d.ts

@@ -1,17 +1,20 @@
 import type { TeamConfig, TeamMember, TeamTask } from '../types/team-config';
 import type { TeamProtocolMessage } from '../types/team-protocol';
+export declare function validateTeamName(teamName: string): void;
+export declare function validateAgentName(agentName: string): void;
+export declare function validateTaskId(taskId: string): void;
 export declare function getTeamsDir(): string;
 export declare function getTasksDir(teamName: string): string;
 export declare function createTeam(config: TeamConfig): void;
 export declare function loadTeamConfig(teamName: string): TeamConfig | null;
-export declare function saveTeamConfig(teamName: string, config: TeamConfig): void;
+export declare function saveTeamConfig(teamName: string, config: TeamConfig): Promise<void>;
 export declare function deleteTeam(teamName: string): void;
-export declare function addTeamMember(teamName: string, member: TeamMember): void;
-export declare function removeTeamMember(teamName: string, agentId: string): void;
-export declare function createTask(teamName: string, task: TeamTask): void;
-export declare function updateTask(teamName: string, taskId: string, updates: Partial<TeamTask>): void;
+export declare function addTeamMember(teamName: string, member: TeamMember): Promise<void>;
+export declare function removeTeamMember(teamName: string, agentId: string): Promise<void>;
+export declare function createTask(teamName: string, task: TeamTask): Promise<void>;
+export declare function updateTask(teamName: string, taskId: string, updates: Partial<TeamTask>): Promise<void>;
 export declare function listTasks(teamName: string): TeamTask[];
 export declare function getTask(teamName: string, taskId: string): TeamTask | null;
-export declare function sendMessage(teamName: string, to: string, message: TeamProtocolMessage): void;
+export declare function sendMessage(teamName: string, to: string, message: TeamProtocolMessage): Promise<void>;
 export declare function readInbox(teamName: string, agentName: string): TeamProtocolMessage[];
 export declare function clearInbox(teamName: string, agentName: string): void;

package/dist/common/src/utils/team-hook-emitter.d.ts

@@ -0,0 +1,40 @@
+import type { TrackEventFn } from '../types/contracts/analytics';
+import type { Logger } from '../types/contracts/logger';
+import type { TeamHookEvent } from '../types/team-hook-events';
+import type { DevPhase } from '../types/team-config';
+/**
+ * Subscribe to all team hook events.
+ * Returns an unsubscribe function.
+ */
+export declare function onTeamHookEvent(listener: (event: TeamHookEvent) => void): () => void;
+/**
+ * Dispatch a team hook event to all registered listeners.
+ * Exported for use in contexts (e.g. CLI) where the full emit helpers
+ * cannot be used because a server-side TrackEventFn is not available.
+ */
+export declare function dispatchTeamHookEvent(event: TeamHookEvent): void;
+export declare function emitTeammateIdle(params: {
+    agentName: string;
+    teamName: string;
+    lastTaskId?: string;
+    trackEvent: TrackEventFn;
+    userId: string;
+    logger: Logger;
+}): void;
+export declare function emitTaskCompleted(params: {
+    taskId: string;
+    taskSubject: string;
+    owner: string;
+    teamName: string;
+    trackEvent: TrackEventFn;
+    userId: string;
+    logger: Logger;
+}): void;
+export declare function emitPhaseTransition(params: {
+    teamName: string;
+    fromPhase: DevPhase;
+    toPhase: DevPhase;
+    trackEvent: TrackEventFn;
+    userId: string;
+    logger: Logger;
+}): void;

package/dist/common/src/utils/team-presets.d.ts

@@ -0,0 +1,35 @@
+import type { TeamRole, DevPhase } from '../types/team-config';
+/**
+ * A preset member definition. Contains the role and descriptive name
+ * but not runtime fields (agentId, joinedAt, status, cwd) which are
+ * assigned at spawn time.
+ */
+export interface PresetMember {
+    name: string;
+    role: TeamRole;
+    agentType: string;
+    model: string;
+}
+/**
+ * A preset configuration that can be used to bootstrap a team.
+ * Contains the member list and default settings but no runtime state.
+ */
+export interface PresetConfig {
+    presetName: string;
+    description: string;
+    defaultPhase: DevPhase;
+    members: PresetMember[];
+    settings: {
+        maxMembers: number;
+        autoAssign: boolean;
+    };
+}
+/**
+ * Returns a preset team configuration by name, or null if not found.
+ * Preset names are case-insensitive.
+ */
+export declare function getTeamPreset(name: string): PresetConfig | null;
+/**
+ * Returns the list of all available preset names.
+ */
+export declare function listPresets(): string[];